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PREFACE 


MANUAL  OBJECTIVES 

This  manual  describes  the  concepts  and  capabilities  of  the 
RSX-llM/M-PLUS  Task  Builder. 

Working  examples  are  used  throughout  this  manual  to  introduce  and 
describe  features  of  the  Task  Builder.  Because  RSX-llM  systems 
support  a  large  number  of  programming  languages,  it  is  not  practical 
to  illusitrate  the  Task  Builder  features  in  all  of  the  languages 
supported.  Instead,  most  of  the  examples  in  the  main  text  of  this 
manual  are  written  in  MACRO-11. 


INTENDED  AUDIENCE 

Before  reading  this  manual,  you  should  be  familiar  with  the 
fundamental  concepts  of  your  operating  system  (RSX-llM  or 
RSX-llM-PLUS)  and  with  the  operating  procedures  described  in  the 
RSX-llM/M-PLUS  MCR  Operations  Manual .  In  addition,  you  should  be 
fimilTar  with  the  programming  concepts  described  in  the  RSX-llM/M-PLUS 
Guide  to  P roc  ram  Development. 


STRUCTURE  OF  THIS  DOCUMENT 

This  manual   has   11   chapters.    Their   contents   are   summarized   as 
follows : 

•  Chapter  1  describes  the  Task  Builder  command  sequences  that 
you  use  to  interact  with  the  Task  Builder. 

•  Chapter  2  describes  the  basic  Task  Builder  functions, 
including  the  Task  Builder's  allocation  of  virtual  address 
space  and  the  resolution  of  global  symbols.  It  also  contains 
an  introduction  to  supervisor-mode  libraries,  privileged 
tasks,  and  multiuser  tasks. 

•  Chapter  3  describes  the  Task  Builder's  overlay  capability  and 
the  language  you  use  to  define  an  overlay  structure. 

•  Chapter  4  describes  the  two  methods  available  to  you  to  load 
overlay  segments. 

•  Chapter  5  describes  some  typical  Task  Builder  features, 
including  tasks  that  access  shared  regions  and  device  commons, 
tasks  that  create  dynamic  regions,  and  virtual  program 
sections. 


PREFACE 

•  Cnapto''  6  defines  privileged  tasks,  describes  their  mapping, 
and  shows  how  to  build  a  privileged  task  to  examine  unit 
control  blocks. 

•  Chapter  7  describes  user-mode  I-  and  D-space,  the  mapping  of 
these  spaces,  and  the  advantages  of  using  T-  and  D-space  in 
user  mode. 

•  Chapter  8  describes  supervisor-mode  libraries.  The  chapter 
defines  and  shows  how  to  build  and  use  supervisor-mode 
libraries. 

•  Chapter  9  describes  and  shows  how  to  build  multiuser  tasks. 

•  Chapter  10  lists  and  describes  the  Task  Builder  switches.  The 
switches  are  listed  in  alphabetical  order. 

•  Chapter  11  lists  and  describes  the  Task  Builder  options.  The 
options  are  listed  in  alphabetical  order. 

This  manual   also   contains   eight   appendices.    Their   contents   are 
summarized  as  follows: 

•  Appendix  A  contains  a  detailed  description  of  the  Task  Builder 
input  data  structures. 

•  Appendix  B  r^ontains  a  detailed  description  of  the  task  image 
file  structure. 

•  Appendix  C  describes  the  considerations  for  building  a  task  on 
one  system  to  run  on  a  system  with  a  different  hardware 
configuration. 

•  Appendix  D  describes  two  memory  dumps:  postmortem  and 
snapshot . 

•  Appendix  E  contains  a  list  of  the  symbols  and  program  section 
names  reserved  for  Task  Builder  use. 

•  Appendix  F  contains  information  on  improving  Task  Builder 
per  f ormance . 

•  Appendix  G  describes  the  fast  Task  Builder. 

•  Appendix  H  contains  the  Task  Builder  error  messages. 
A  Task  Builder  gloss,  y  follows  the  appendices. 


ASSOCIATED  DOCUMENTS 

Other  manuals  closely  allied  with  this  document  are  described  in  the 
Information  Directory  and  Master  I ndex  for  your  operating  system. 
This  directory  defines  the  intended  audience  of  each  manual  in  the 
documentation  set  and  provides  a  brief  synopsis  of  each  manual's 
contents . 
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PREFACE 

CONVENTIONS  OSED  IN  THIS  DOCUMENT 

In  this  manual,  horizontal  ellipses  (...)  indicate  that  additional, 
optional  arguments  in  a  statement  format  have  been  omitted.  For 
example: 

Input-spec , . . . 

means  that  one  or  more  input-spec  items,  separated  by  commas,  can  be 
specified . 

Vertical  ellipses  mean  that  lines  in  an  example,  command  lines,  or 
lines  in  a  Task  Builder  map  file  that  are  not  pertinent  to  an  example 
have  been  omitted.   For  example: 

TKB>  input-1 ine 


means  that  one  or  more  of  the  indicated  TKB  items  have  been  omitted. 

The  words  "Task  Builder"  in  this  manual  have  been  abbreviated  to  \,he 
acronym  TKB. 

Unless  otherwise  stated,  references  to  tasks,  their  mapping,  and  their 
structure  imply  a  nonpr i vi leged  task  in  an  RSX-llM  mapped  system. 

In  the  examples  of  Task  Builder  command  sequences,  the  portion  of  the 
command  sequence  that  you  type  is  printed  in  red.  The  Task  Builder's 
responses  and  prompts  are  printed  in  black. 

Shading  in  the  manual  has  the  following  meanings: 

pink     Indicates  that  the  text  describes  features  appearing  only 
on  RSX-llM  operating  systems. 

gray    Indicates  that  the  text  describes  features  appearing  only 
on  RSX-llM-PLUS  operating  systems. 
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SUMMARY  OF  TECHNICAL  CHANGES 


This  manual  contains  the  changes  for  RSX-llM  Version  4.1  and 
RSX-llM-PLUS  Version  2-1.  This  manual  has  been  extensively  revised. 
A  study  of  the  Table  of  Contents  ard  this  Suiwnary  of  Tecimical  Changes 
is  recommended  before  you  look  for  information  in  the  manual. 


GENERAL  CHANGES 

Editorial   changes   were   made   throughout   the   manual    to   correct 
typographical  errors. 

Small  technical  changes  were  made  throughout  the  manual  as  a  result  of 
ongoing  development,  SPR  responses,  and  readers'  comments. 

The  major  technical  changes  to  the  manual  are  listed  below. 


TECHNICAL  CHANGES 

NEW  OPTIONS 

DSPPAT  --  Allows  object-level  patching  of  i  conventional  task  or 
the  D-space  part  of  an  I-  and  D-space  task. 

CHANGED  OPTIONS 

ABSPAT  --  Allows  object-level  patching  of  a  conventional  task  or 
the  I -space  part  of  an  I-  and  D-space  task. 

COMMON  --  The  COMMON  option  causes  the  common  to  be  mapped  with 
D-space  APRS.  Therefore,  for  I-  and  D-space  tasks,  the  common 
can  contain  data  only. 

EXTTSK  —  Extends  the  D-space  portion  of  an  I-  and  D-space  task. 
Because  libraries  are  mappec?  with  both  I-space  APRs  and  D-space 
APRS,  extending  the  D-space  of  I-  and  D-space  tayks  may  cause 
unmapping  of  the  library's  D-space  APRs,  which  causes  the  library 
to  be  mapped  in  I-space  only. 

LIBR  —  The  LIBR  option  causes  the  library  to  be  mapped  with  both 
I-space  and  D-space  APRs  when  linked  to  an  I-  and  D-space  task. 

RESCOM  —  The  RESCOM  option  causes  the  common  to  be  mapped  with 
D-  space  APRs.  Therefore,  for  I-  and  D-space  tasks,  the  common 
can  contain  data  only. 

RESLIB  —  The  RESLIB  option  causes  the  library  to  be  mapped  with 
both  I-space  and  D-space  APRs  when  linked  to  an  I-  and  D-space 
task . 
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NEW  ERROR  MESSAGES 

Module  module-name  contains  incompatible  autoload  vectors 

CHANGED  ERROR  MESSAGES 

Lookup  failure  resident  library  file 

changed  to 
Lookup  failure  resident  library  file  -  filename. ext 

MISCELLANEOUS  TECHNICAL  CHANGES 

Autoload  vectors  for  conventional  tasks  have  changed.  The  call 
to  $AUTO  is  now  made  indirectly  through  .NAUTO  in  the  overlay 
impure  area. 

I-  and  D-space  tasks  may  be  overlaid  by  using  either  autoload  or 
manual  load. 

Autolo<^d  vectors  for  I-  and  D-space  tasks  have  a  format  different 
from  those  of  conventional  tasks.  The  autoload  vectors  for  I- 
and  D-space  tasks  contain  an  I-space  part  located  in  the  task's 
I-space  and  a  D-space  part  located  in  the  task's  D-spac«r 

Memory  allocation  diagrams  may  be  userJ  as  an  aid  to  create  .ODL 
f  i les  . 

Overlay  Run-time  System  routines  have  changed  size  from  the 
previous  release. 

MACRO-11  and  FORTRAN  manual  load  calling  sequences  for  overlays 
in  I-  and  D-space  tasks  may  not  use  asynchronous  loading. 

For  versions  of  TKB  that  support  I-  and  D-space   tasks  and   that 

were  used   to  build  libraries,  TKB  allocates  autoload  vectors  in 

the  root  of  the  task  only  for  those  autoloadable  entry  points  in 
the  library  referenced  by  the  task. 

I-  and  D-space  tasks  may  link  to  commons,  conventional  libraries, 
and  supervisor-mode  libraries. 

Loading  I-  and  D-space  tasks  into  memory  requires  two  disk 
accesses.  Overlaid  I-  and  D-space  tasks  may  require,  in 
additior.,  two  disk  accesses  for  loading  each  segment  if  the 
segment  contains  both  l-space  and  D-space. 

Segment  descriptors  for  I-  and  D-space  tasks  contain  an  extension 
for  the  D-space  part. 

Only  one  level  of  overlay  is  allowed  in  supervisor-mode 
1 ibrar ies . 

T-  and  D-space  multiuser  tasks  are  allowed.  TKB  uses  four  window 
blocks  to  map  these  tasks. 

Internal  Symbol  Directory  Records,  along  with  their  formats,  are 
described  in  Appendix  A,   They  consist  of: 

•  Type  1  records,  generated  by  TKB  and  output  to  the  .STB  file 

•  Type  2  records,  generated  by  language  processors 
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•  Type  3  records,  created  from  type  2  records  and  output  to   Lhe 
.STB  file 

•  Type  4  records,  written  to  the  .STB  file  without  modification 

A  new  bit  called  LD$TYP  distinguishes  between  a  library  or  common. 
See  offset  R$LFLG  in  the  resident  library  name  block  data  in  Appendix 
B. 

The  first  library  in  a  cluster  may  be  overlaid  and  contain  a  non-null 
root. 

New  Task  Builder  reserved  symbols  have  been  added  to  Appendix  E. 

The  Fast  Task  Builder  supports  the  /EA  switch  and  the  TASK=  option. 

The  map  format  for  an  I-  and  D-space  task  shows  both  I-  and  D-space 
contributions  to  a  segment  and  the  disk  blocks  that  contain  data 
sections. 

Other  minor  technical  and  editorial  changes  have  been  made  also. 
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CHAPTER  1 
INTRODMCTION  AND  COMMAND  SPECIFICATIONS 

The  basic  steps  in  dr/eloping  a  program  are  as  follows: 

1.  you  vrite  one  or  more  routines  in  an  RSX-1 IM/M-PLUS  supported 
souice  language  and  enter  each  routine  as  an  ASCII  text  file, 
through  an  editor. 

2.  You  submit  each  text  file  to  the  appropriate  language 
translator  (an  assembler  or  compiler),  which  converts  it  to  a 
relocatable  object  module. 

3.  You  specify  the  object  modules  as  input  tc  the  Task  Builder 
(TKB) ,  which  combines  the  object  modules  into  a  single  task 
image  output  file. 

4.  You  install  and  run  the  task. 

If  you  find  errors  in  the  task  when  you  run  it,  you   make   corrections 
to  the  text  file  using  the  editor,  and  then  repeat  steps  2  through  4. 


The  Task  Builder's  main  function 
modules  (.OBJ  files)  into 
install  and  run  on  a 


is   to   convert   relocatable  object 

_  __  a  single  task  image  (.TSK  file)  that  you  can 

...^^ui.x  u..^  i.^..  v^..  c  RSX-llM  or  RSX-llM-PLUS  system.   The  task  is   the 
fundamental  executable  unit  in  both  systems. 


If  your  program  consists  of  a  single  object  module,  using  the  Task 
Builder  (TKB)  is  appropriately  simple.  You  specify  as  input  only  the 
name  of  the  file  containing  the  object  module  produced  from  the 
translation  of  the  program,  and  specify  as  output  the  task  image  file. 

Typically,  however,  programs  consist  of  more  than  a  single  object 
module.  In  this  case,  you  name  each  of  the  object  module  files  as 
input.  TKB  links  the  object  mr lules,  resolves  references  between 
them,  resolves  references  to  the  system  library,  and  produces  a  single 
task  image  ready  to  be  installed  and  executed. 

TKB  makes  a  set  of  assumptions  (defaults)  about  the  task   image   based 

on   typical   usage   and   storage  requirements.   You  can  override  these 

assumptions  by  including  switches  and   options   in  the   task-building 

terminal  sequence.  Thus,  you  can  build  a  t='sk  that  is  tailored  to  its 
own  input/output  and  storage  requirements. 

TKB  also  pro.luces  (upon  request)  a  memory  allocation  (map)  file  that 
contains  information  describing  the  allocation  of  address  space,  the 
modules  that  make  up  the  task  image,  and  the  value  of  all  global 
symbols.  In  addition,  you  can  requrst  that  a  list  of  global  symbols, 
accompanied  by  thp  namf  nf  parh  rf>f prenci  nn  Ti^d'ile,  b«»  appended  to  the 
tile  (global  cross  reference). 
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Note  that  the  examples  in  this  manual  use  MCR  as  the  operating  system 
language.  Refer  to  the  RSX-llM-PLUS  Command  Language  Manual  and,  in 
particular,  to  the  command  in  that  manuil  for  DIGITAL  Command  Language 
equivalence . 

The  following  example  shows  a  simple  sequence  for  building  a  task: 

>MAC  PROG=PROG 

>TKB  PROG=PROG 

>IHS  PROG 

>RUN  PROG 

The  first  command  (MAC)  causes  the  MACRO-11  assembler  to  translate  the 
source  code  of  the  file  PROG. MAC  into  a  relocatable  object  module  in 
the  file  PROG. OBJ.  The  second  command  (TKB)  causes  TKB  to  process  the 
file  PROG. OBJ  and  to  produce  the  task  image  file  PROG.TSK.  The  third 
command  (INS)  causes  the  INSTALL  processor  to  add  the  task  to  the 
Executive's  directory  of  executable  tasks  (System  Task  Directory). 
The  fourth  command  (RUN)  causes  the  task  to  execute. 

The  example  just  given  includes  the  command 

>TKB  PROG=PROG 

This  command  illustrates  the  simplest  use  of  TKB.  It  gives  the  name 
of  a  single  file  as  output  and  the  name  of  a  single  file  as  input. 

The  following  sections  describe  basic  Task  Builder  command  forms  and 
sequences. 


1.1   TASK  COMMAND  LINE 

The   task   command   line   contains   the   output   file  specifications, 

followed   by   the  input  file  specifications;   they  are  separated  by  an 

equal  sign  (=).   You  can  specify  up  to   three   output  files   and   any 
number  of  input  files. 

The  task  command  line  has  the  following  form: 

task- image- fi le,map-f i le,symbol-def ini tion-f i le= input- file, . . . 


You  must  give  the  output  files 
you  name  is  the  image  (.TS 
allocation  (.MAP)  file;  and  th 
file.  The  map  file  lists  inf 
components  within  the  task.  Th 
global  symbol  definitions  in  th 
addresses  in  a  format  suitable 
this  file  when  you  are  bui 
(Resident  libraries  and  commons 
combines  the  input  files  to 
installed  and  executed. 


in  a  specific  order:    th 
K)   file;    the   second 
e  third  is  the  symbol  def 
ormation  =■'  >ut  the  size  a 
e  symbol  definition  file 
e  task  and  their  virtual 
for  reprocessing  by  TKB. 
Iding   a   resident   libra 
are   described   in   Cha 
create  a  single  task  ima 


e  first  file 
is  the  memory 
inition  (.STB) 
nd  location  of 
contains  the 
or  relocatable 
You  specify 
ry  or  common, 
pter  3.)  TKB 
ge  that  can  be 


1.1.1   Printing  the  Map  File 

If  you  create  a  map  file  by  specifying  one  in 
there  are  a  number  of  ways  that  you  can  print 


the 
the 


TKB 
file, 


examples  show  you  ways  that  you  may  print  the  map  fil<3, 


command   line. 
The  following 


1.  With  the  following  two  command  lines,  you  can  create  a  map 
file  and  then  print  it  later.  The  TKB  command  line  tells  TKB 
to  create  a  task  file,  a  map  file  without  printing  it  (by  use 
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of  the  switch  /-SP) ,  and  a  symbol  definition  file.   The  PRINT 
command  line  tells  the  system  to  print  the  map  file. 

>TKB  INV.TSK,IN/.MAP/-SP, INV . STB- INV . OB J 
>PRINT  INV.MAP 

2.  With  the  next  command  line,  you  can  princ  the  map  file 
directly  as  it  is  created.  In  this  case,  TKB  tells  tho 
system  to  print  the  file  by  use  of  the  switch  /SP.  However, 
the  system  task  PRT...  or  . . . PRT  must  be  installed  for  this 
method  to  work. 

>TKB  INV.TSK, INV. MAP/SP , I NV . STB= INV . OBJ 

3.  With  the  next  command  line,  you  can  print  the  map  file  on  a 
line  printer  that  you  specify.  It  is  best  to  use  this 
command  line  on  an  RSX-llM-PLUS  system  because  that  system 
uses  transparent  spooling.  Using  this  command  line  on  an 
RSX-llM  system  may  cause  the  printer  to  be  unavailable  to 
other  tasks.  See  your  system  manager  for  specific  details 
about  using  the  following  ccm'^iand  line. 

>TKB  INV.TSK.LPn: ,SY: INV.STB= INV.OBJ 


1.1.2   Omitting  Specific  Outj-jt  Files 

You  can  omit  any  output  file  by  replacing  the  file  specification   with 

the   delimiting   comma  that  would  normally  follow  it.   The  following 

commands  iilustraCte  the  ways  in  which  TKB  interprets  the   output   file 
names. 

Command  Output  Piles 

>'  <B  IMGl, IMCl,  IMG1  =  IN;   The  task  image   file   is   IMGl.TSK,  the 

memory     allocation    (map)    file  is 

IMGl, MAP,  and  the  symbol  definition  file 
is  IMGT.STB. 

>TKB  IMG1=IN1  The  task  image  file  is  IMGl.TSK. 

>TKB  ,IMG1=IN1  The  map  file  is  IMGl. MAP. 

>TKB   ,,IMG1=IN1  The  symbol  definition  file  is  IMGl. STB. 

>TKB  IMGl, , IMG1=IN1      The  task  image  file  is  IMGl.TSK  and   the 

symbol  definition  file  is  IMGl. STB. 

>TKB  =IN1  This  is  a  diagnostic  run  with  no   output 

f i les. 


1.2   MOLTILINE  INPUT 

Although  you  can  specify  a  maximum  of  three  output  files,  you  can 
specify  any  number  of  input  files.  When  you  specify  several  input 
files,  a  more  flexible  format  is  sometimes  necessary  --  one  that 
consists  of  several  lines.  This  multiline  format  is  also  necessary 
when  you  want  to  include  options  in  your  commano  sequence  (see  Section 
1.3)  . 
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If  you  type  TKB,  the  Monitor  Console  Routine  (MCR)  activates  the  Task 
Builder.  TKB  then  prompts  for  input  until  it  receives  a  line 
consisting  only  of  the  terminating  slash  characters  (//) .  For 
example : 

>TKB 

TKB>IMG1, rMGl=INl 

TKB>IN2,IN3 

TKB>// 

This  sequence  produces  the  same  result  as  the  single  line  command 

>TKB  IMGl, IMG1=IN1, IN2, IN3 

Both  command  sequences  produce  the  task  image  file  IMGl.TSK  and  the 
map  file  IMGl. MAP  from  the  input  files  INI. OBJ,  IN2.0BJ,  and  IN3.0BJ. 

You  must  specify  the  output  file  specifications  and  the  equal  sign  (») 
on  the  first  command  line.  You  can  begin  or  continue  input  file 
specifications  on  subsequent  lines. 

When  you  type  the  terminating  slash  characters  (//) ,  TKB  stops 
accepting  input,  builds  the  task,  and  returns  control  to  MCR. 


1.3   OPTIONS 

You  use  options  to  specify  the  characteristics  of  the  task  you  are 
building.  To  include  options  in  a  task,  you  must  use  the  multiline 
format.  If  you  type  a  single  slash  (/)  following  the  input  file 
specification,  TKB  requests  option  information  by  displaying  ENTER 
OPTIONS:   and  prompting  for  input.   For  example: 

>TKB 

TKB>IMGI, IMG1=INI 

TKB>IN2, IN3 

TKB/ 

Enter  Options: 

TKB>PRI=100 

TKB>COMMON=JRNAL:RO 

TKB>// 

In  this  sequence  there  are  two  options:  PRI=100  and  COMMON=JRNAL: RO. 
The  two  slashes  end  option  input,  initiate  the  task  build,  and  return 
control  to  MCR  upon  completion. 

NOTE 

When  you  are  building  an  overlaid  task, 
there  are  exceptions  to  the  use  of  the 
single  slash  (/) .  Overlaid  tasks  are 
described  in  Chapter  4. 

The  RSX-llM/M-PLUS  Task  Builder  provides  numerous  options,  which  are 
described  in  Chapter  11.  The  general  form  of  an  option  is  a  keyword 
followed  by  an  equal  sign  (=)  and  an  argument  list.  The  arguments  in 
the  list  are  separated  from  one  another  by  a  colon  (:).  In  the 
example  above,  the  first  option  consists  of  the  keyword  PRI  and  a 
single  argument  indicating  that  the  task  is  to  be  assigned  the 
priority  100.  The  second  option  consists  of  the  keyword  COMMON  and  an 
argument  list,  JRNAL:RO,  indicating  that  the  task  accesses  a   resident 
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common  region  named  JRNAL  and  that  the  access  is  read-only.  You  can 
specify  more  than  one  option  on  a  line  by  using  an  exclamation  point 
(!)  to  separate  the  options.   For  example,  the  command 

TKB>PRI=100 !COMMON=JRNAL: RO 

is  equivalent  to  the  two  lines: 

TKB>PRI=100 
TKB>COMMON=JRNAL: RO 

Some  options  accept  n.ore  than  one  set  of  argument  lists.  You  use  a 
comma  (,)  to  separate  the  argument  lists.   For  example,  in  the  command 

TKB>COMMON=JRNAL:RO,RFIL:RW 

the   first   argument   list   indicates   that   the   task  has   requested 

read-only   access   to   the  resident  common  JRNAL.   The  second  argument 

list  indicates  that  the  task  has  requested  read/write  access  to  the 
resident  common  RFIL. 

The  following  three  sequences  are  equivalent: 

TKB>COMMON=JRNAL:RO,RFIL:RW 

TKB>COMMON= JRNAL : RO ! COMMON=RF I L : RW 

TKB>COMMON=JRNAL: RO 
TKB>COMMON=RFIL:RW 


1.4   MULTIPLE  TASK  SPECIFICATIONS 

If  you  intend  to  build  .iiore  than  one  task,  you  can  use  the  single 
slash  (/)  following  option  input.  This  directs  TKB  to  stop  accepting 
input,  build  the  task,  and  '  request  information  for  the  next  task 
build.   For  example: 

>TKB 

TKB>IMG1=IN1 

TKB>IN2, IN3 

TKB>  ' 

Enter  Options: 

TKB>PR1=100 

TKB>COMMON=JRNAL:RO 

TKB>/ 

TKB>IMG2=SUB1 

TKB>// 

TKB  accepts  the  output  and  input  file  specifications  and  the  option 
input;  it  then  stoos  accepting  input  upon  encountering  the  single 
slash  (/)  during  optioi  input.  TKB  builds  IMGl.TSK  and  then  returns 
to  accept  more  Input  fjr  building  IMG2.TSK. 


1.5   INDIRECT  COMMAND  FILES 

You   can   enter   commands   to   TKB  directly   from   the   keyboard,   or 

indirectly   through   the   indirect  command  file  facility.   To  use  the 

indirect  command  file  facility,  you  prepare  a  file  that   contains   the 
TKB   commands   you   want  to  be  executed.   Later,  after  you  invoke  TKB, 

you  type  an  at  sign  (@)  followed  by  the  name  of  the   indirect   command 
file. 
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For  example,  suppose  you  create  a  file  called  AFIL.CMD  containing  the 
following: 

IMGl, IMG1=IN1 

I N  2  ,  I N  3 

/ 

PRI=100 

COMMON=JRNAL:RO 

// 

Later,  you  can  type: 

>TKB 

TKBXaAFIL 

TKB> 

or  simply: 

>TKB  §AFIL 

When  TKB  encounters  the  at  sign  (0)  ,  it  directs  its  search  for 
commands  to  the  file  named  AFIL.CMD.  The  example  above  is  equivalent 
to  the  keyboard  sequence 

>TKB 

TKB>IMG1, IMG1=IN1 

TKB>IN2, IN3 

TKB>/ 

Enter  Options: 

TKB>PRI=100 

TKB>COMMON  =  JRNAL:  RO 

TKB>// 

When  TKB  encounters  two  terminating  slash  characters  (//)  in  the 
indirect  command  file,  it  terininates  indirect  command  file  processing, 
builds  the  task,  and  exits  to  MCR. 

When  TKB  encounters  a  single  slash  (/)  in  an  indirect  command  file  and 

the   slash   is   the  last  character  in  the  file,  TKB  directs  its  search 

for  commands  to  the  terminal.   For  example,  suppose  the  file   AFIL.CMD 

in  the  last  example  is  changed  to  read: 

IMGl, IMG1=IN1 
IN2, IN3 

/ 

Later,  you  can  type: 

>TKB 
TKB>(?AFIL 

In  this  case,  TKB  goes  to  the  terminal  and  prompts: 

Enter  Options: 
TKB> 

From  this  po^nt,  you  input  options  to  TKB  directly  from  the  keyboard. 
If  you  then  conclude  option  input  from  the  keyboard  with  double 
slashes  (//) ,  TKB  suspends  command  processing,  as  described  above,  and 
exits  to  MCR  following  the  task  build.  If  you  conclude  option  input 
with  a  single  slash  (/) ,  TKB  prompts  for  new  command  input  following 
t'.e  task  build  of  IMGl.TSK,  as  follows: 

TKB> 
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Using  the  single  slash  (/)  following  option  input  in  indirect  command 
files  is  d  convenient  way  to  return  control  to  your  terminal  between 
successive  task  builds.  For  example,  suppose  you  create  two  indirect 
command  files.   The  first,  AFIL.CKD,  contains: 

IMGl, IMG1=IN1 
IN2,  IN3 

/' 

PRI=100 

COMMON=JRNAL 

/ 

The  second,  AFIL1.CMD,  contains: 

IMG2, IMG2=IN4 

INS, IN6 

/ 

PRI=100 

// 

Then,  the  terminal  sequence  to  build  these  two  tasks  is: 

>TKB 

TKB>9AFIL 
TKBxaAFILl 
> 


NOTE 

For  interaction  with  a  TKB  indirect 
command  file  as  described  above,  you 
must  use  the  multiline  format  when  you 
specify  the  indirect  command  file. 

TKB  permits  two  levels  '^f  indirection  in  file  references.  That  is, 
the  indirect  command  file  referenced  in  a  terminal  sequence  can 
contain  a  reference  to  another  indirect  command  file.  For  example,  if 
the  file  BFIL.CMD  contains  all  the  standard  options  that  are  used  by  a 
particular  group  of  users  at  an  installation,  you  can  modify  AFIL  to 
include  an  indirect  command  file  reference  to  BFIL.CMD  as  a  separate 
line  in  the  option  sequence. 

The  contents  of  AFIL.CMD  would  then  be: 

IMGl, IMG1= INI 

IN2,  IN3 

/ 

PRI=100 

COMMON=JRNAL:RO 

@BFIL 

// 

To  build  these  files,  you  type: 

>TKB 

TKB>  ?AFIL 

Suppose  the  contents  of  BFIL.CMD  are: 

STACK=100 
aNITS=5!ASG=DTl:5 
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Then  the  terminal  equivalent  of  boilding  these  files 


is : 


>TKB 

TKB>IMG1, IMG1=IN1 

TKB>IN2, IN3 

TKB>  / 

Enter  Options: 

TKB>PRI=100 

TKB>COMMON=JRNAL:RO 

TKB>STACK=100 

TKB>UNITS=5 1 ASG=DT1 : 5 

TKB>// 

The  indirect  command  file  reference  must  appear  on  a  separate  line. 
For  example,  if  you  modify  AFIL.CMD  by  adding  the  9BFIL  reference  on 
the  same  line  as  the  COMMON=JRNAL: RO  option,  the  substitution  would 
not  take  place  and  TKB  would  repoit  an  error. 


1.6   COMMENTS  IN  LINES 

You  can  include  comments  at  any  point  in  the  command  sequence,  except 
in  lines  that  contain  file  specifications.  You  begin  a  comment  w'.th  a 
semicolon  ( ; )  and  terminate  it  with  a  carriage  return.  All  tex»; 
between  these  delimiters  is  a  comment. 

For  example,  in  the  indirect  command  file  AFIL.CMD,  described  in 
Section  1.5,  you  can  add  comments  to  provide  more  information  about 
the  purpose  and  the  status  of  the  task. 


TASK  33A 

DATA  FROM  GROUP  E-46  WEEKLY 
IMGl, IMG1« 

PROCESSING  ROUTINES 
INI 

STATISTICAL  TABLES 
IN2 

; 

}  ADDITIONAL  CONTROLS 

IN3 

/ 

PRI=100 


COMMON=JRNAL:RO  ;  RATE  TABLES 

TASK  STILL  IN  DEVELOPMENT 
// 


1.7   FILE  SPECIFICATIONS 

TKB  adheres   to   the   sLdiidaLd   R3X-1 
specifications.    For   any   file,  you 
File  Directory  (UFO),  the  file  name, 
number,  and  any  number  of  switches. 


IM/M-TL'JS   conventions   for   file 

can  specify  the  device,  the  User 

the  file  type,  the   file   version 
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The  file  specification  has  the  form 

device: Igroup,member ) f i lename. type; vers ion/swl/sw2. . ./swn 

When  you  specify  files  by  name  only,  TKB  applies  the  default  switch 
settings  for  device,  group,  member,  type,  and  version. 

For  example: 

>TKB 

TKB>iMGl, IMG1=IN1 

TKB>IN2,IN3 

TKB>// 

If  the  current  User  Identification  Code  (UIC)  of  the  terminal  that  TKB 
is  running  on  is  [200,200],  the  task  image  file  specification  of  the 
example  is  assumed  to  be: 

SYO: [200,200] IMG1.TSK;1 

That  is,  TKB  creates  the  task  image  file  on  the  system   device   (SYO:) 

under   UFD   [200,200].   The  default  type  for  a  task  image  file  is  .TSK 

and,  if  the  name  IMGl.TSK  is   new,  the   version   number   is   1.    The 

default   settings   for  all  the  task  image  switches  also  apply.   Switch 

defaults  are  described  in  detail  in  Chapter  6. 

For  example: 

>TKB 

TKB> [ [20,23] 1 IMG1/CP/DA,IMG1/CR=IN1 

TKB>IN2; J, IN3 

TKB>// 

This  sequence  of  commands  instructs  TKB  to  create  a  task  image  file 
IMG1.TSK;1  and  a  memory  allocation  (map)  file  IMG1.MAP;1  (actually,  it 
produces  IMGl.TSK  and  IMGl.MAP  with  versions  one  higher  than  the 
current  versions)  under  UFD  [20,23]  on  the  device  SY:.  The  task  image 
is  checkpointable  and  contains  the  standard  debugging  aid  (ODT) .  TKB 
outputs  the  map  to  the  line  printer  with  a  global  cross-reference 
listing  appended  to  it.  TKB  builds  the  task  from  the  latest  versions 
of  INI. OBJ  and  IN3.0BJ,  and  the  specific  version  of  IN2.0BJ.  The 
input  files  are  all  found  on  the  system  device. 

The  system  device  (SY:)  is  always  the  default  device  unless  you 
specify  otherwise.  If  you  specify  another  device  on  either  side  of 
the  equal  sign,  that  device  becomes  the  default  device  for  the  files 
on  that  side  of  the  equal  sign.   For  example: 

>TKB 

TKB> [ [20,23] 1 IMGl, IMGl , IMG1=DB 1 : IMCl , INI , IN2 

This  command  line  produces  a  task  image  file,  map  file,  and  listing 
file  in  UFD  [20,23]  on  device  SY:.  All  the  object  files  are  in  UFD 
[20,23]  on  device  DBl.  In  cases  where  files  are  scattered  among 
several  devices,  the  devices  must  be  specified  in  the  command  line. 

For  some  files,  a  device  specification  is  sufficient.  In  the  example 
above,  the  nap  file  c-uld  be  fully  specified  by  the  device  LP:.  The 
map  listing  is  produced  on  the  line  printer,  but  is  not  retained  as  a 
file. 

This  example  also  used  switches  /CP,  /CR,  and  /DA.  The  code,  syntax, 
and  meaning  for  each  switc-  are  given  in  Chapter  6. 
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1.8   SUMMARY  OF  SYNTAX  RULES 

The  syntax  rules  for  issuing  commands  to  TKB  are  as  follows: 

•   A  task-build  command  can  take  any   one   of   four   forms.    The 
first  form  is  a  single  line: 

>TKB  task-command-line 

The  second  form  has  additional  lines  for  input  file  names: 

>TKB 

TKB> task -command- 1 ine 

TKB> input-line 

TKB> terminating -symbol 

The  third  form  allows  you  to  specify  options: 

>TKB 

TKB> task -command- line 

TKB>/ 

Enter  Options: 

TKB>option-iine 

• 
• 

TKB> terminating -symbol 

The  fourth  form  has  both  input  lines  and  option  lines: 

>TKB 

TKB> task-command- line 

TKB> input-line 


TKB>  / 

Enter  Options: 

TKB>option-line 


TKB > terminating -symbol 
The  terminating  symbol  can  be: 

/    if  you  intend  to  build  more  than  one  task 

//   if  you  want  TKB  to  return  control  to  MCR 
A  task  command  line  has  one  of  the  three  form!»: 

output-fi l2-list=input-f i le, . . . 

=input-f i le, . . . 

@indirect-command-f i le 

The  third  form  is  an  indirect  command  file   specification,   as 
described  in  Section  1.5. 
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•  An  output  file  list  has  one  of  the  three  forms: 

task-image-f il  ,map-f i le, symbol-def ini t ion-f i le 

task- image- file, map- file 

task-image-f i le 

The  task-image-file  is  the  file  specification  for  the  task 
image  file;  map-file  is  the  file  specification  for  the  memory 
allocation  (map)  file;  and  lymbol-def ini t ion-f i le  is  the  file 
specification  for  the  symbol  definition  file.  Any  of  the 
specf ications  can  be  omitted,  so  that,  for  example,  the 
following  form  is  permitted: 

task-image-f ile, , symbol-def ini t ion-f i le 

•  An  input  line  has  one  of  two  forms: 

input-f i le , . . . 

0 i nd irect- command- fi le 

Both  input-file  and  indirect-command-file  are  file 
specifications . 

•  An  option  line  has  one  of  two  forms: 

option! . . . 

8  indirect-command- file 
The  indirect-command-file  is  a  file  specification. 

•  An  option  has  the  form: 

keyword=argument-list , . . . 
The  argument-list  is: 

arg  : .  .  . 
The  syntax  for  each  option  is  given  in  Chapter  6. 

•  A   file   specification   conforms   to   standard    RSX-IM/M-PLUS 
conventions.   It  has  the  form: 

device  :  [group, member] f ilename. type; vers ion/swl/sw2 /swn 

device: 

The  name  of  the  physical  device  on  which  the  volume 
containing  the  desired  file  is  mounted.  The  name  consists 
of  two  ASCII  characters  followed  by  an  optional  1-  or 
2-digit  octal  unit  number  and  a  colon;  for  example,  LP: 
or  DTI: . 

group 

The  group  numb-^r ,  in  the  range  of  1  through  377(8). 
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member 

The  member  number,  in  the  range  1  through  377(8). 

filename 

The  name  of  the  desired  file.   The  file  name  can  contain  up 
to  9  alphanumeric  characters. 


type 


The  3-character  file  type  identification.  Files  having  the 
same  name  but  a  different  function  are  distinguished  from 
one  another  by  the  file  type;  for  example,  CALC.TSK  and 
CALC.OBJ. 


version 


The  version  number,  in  octal,  of  the  file.  Various 
versions  of  the  same  file  are  distinguished  from  one 
another  by  this  number;  for  example,  CALC.0BJ;1  and 
CALC.OBJ; 2. 

All  components  of  a  file  specification  are  optional.  The 
combination  of  the  group  number  and  the  member  number  is 
the  User  File  Directory  (UFD)  that  contains  the  file  name. 


1-12 


The  process  of  building 
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CHAPTER  2 
TASK  BUILDER  FUNCTIONS 

a  task  involves  three   distinct   Task   Builder 


1.  Linking  object  modules 

2.  Assigning  addresses  to  the  task  image 

3.  Building  data  structures  into  the  task 

First,  TKB  is  a  linker.  It  collects  and  links  the  relocatable  object 
modules  that  you  specify  to  it  into  a  single  task  image,  and  resolves 
references  to  global  symbols  across  the  module  boundaries. 

Second,  TKB  assigns  addresses  to  the  task  image.  On  mapped  systems, 
TKB  assigns  addresses  for  a  task  beginning  at  0.  The  Executive  then 
relocates  the  addresses  at  run  time.  On  unmapped  systems,  TKB  assigns 
addresses  for  a  task  beginning  at  the  base  address  of  the  partition  in 
which  the  task  is  to  run.  The  addresses  of  tasks  that  run  on  unmapped 
systems  are  not  relocated  at  run  time. 


NOTE 

Unless  otherwise  indicated,  references 
to  tasks  that  run  on  mapped  systems 
assume  that  the  tasks  are  nonpr i vi leged 
and  residing  within  system-controlled 
partitions . 


Third,  TKB  builds  data  structures  into 
required  by  the  INSTALL  procesror  to 
Executive  to  run  it. 


the   task   image   that   ate 
install  the  task  and  by  the 


This  chapter  describes  the  three  TKB  functions  in  detail.  It  also 
describes  the  concepts  of  mapped  and  unmapped  systems.  In  addition, 
this  chapter  introduces  regions,  supervisor-mode  libracies,  overlays, 
privileged  tasks,  I-  and  D-space  tasks,  and  many  of  the  mapping 
concepts  necessary  for  an  understanding  of  task  mapping  and  Task 
Builder  functions. 


2.1   LINKING  OBJECT  MODULES 

TKB  links  object  modules 
resolves  references  t 


lies  within  the  context  of   program 
o  global  symbols  across  module  bou 


sections 
ndar ies . 


and 


When  the  language  translators  convert  symbolic  source  code  within  a 
module  to  object  code,  they  assign  provisional  16-bit  addresses  to  the 
code.   A  single  assembly   or   compilation   produces   a   single   object 
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module.  In  its  simplest  form,  each  module  begins  at  0  and  extends 
upward  to  the  highest  address  in  the  module.  Three  object  modules 
produced  at  separate  times  might  have  the  address  limits  shown  in 
Figure  2-1  . 


1000- 


RELOCATABLE  0- 


MODULE  «1 


5CX)- 


RELOCATABLE  0- 


750 


MODULE  r2 


RELOCATABLE  0 


Figure  2-1   Relocatable  Object  Modules 


If  these  modules  represent  the  separate  modules  of  a  single  program, 
TKB  l.nks  them  together  and  modifies  the  provisional  addresses  to  one 
of  the  f ol lowi  ng : 

•  For  a  mapped  system,  a  single  sequence  of  addresses  beginning 
at  0  and  extending  upward  to  the  sum  of  the  lengths  of  all  the 
modules  (-1  byte) 

•  For  an  unmapped  system,  a  single  sequence  of  addresses 
beginning  at  a  base  address  assigned  at  task-build  time  and 
extending  upward  to  the  sum  of  the  lengths  of  all  the  modules 
(-1  byte) 

For  example,  Figure  2-2  shows  the  three  modules  linked  for  a  mapped 
system  and  the  modules  linked  for  an  unmapped  system. 


2.1.1   Allocating  Program  Sections 

The  language  translators  process  source  code  and  TKB  links  object 
modules  within  the  context  of  program  sections.  A  program  section  is 
a  block  of  code  or  data  that  consists  of  three  elements: 

•  A  name 

•  A  set  of  attributes 


•   A  length 

A  program  section  is  the  basic  unit   used   by 
placement   of  code  and  data  in  a  task  image, 
maintain  a  separate  location  counter  for  each 
program.    The   name   of  each  program  section, 


TKB   to  determine   the 

The  language  translators 

program   section   in   a 

its  attributes,  and  its 


length  are  conveyed  to  TKB  through  the  object  module, 
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2250 


MODULE  c3 


MODULE  r2 


MODULE  «1 


3250- 


BASE  1  GOO- 


MODULE  »3 


MODULE  »2 


MODULE  »1 


MAPPED 
SYSTEM 


UNMAPPED 
SYSTEM 


Figure  2-2   Modules  Linked  for  Mapped  and  Unmapped  Systems 


You  can  create  as  many  program  sections  within  a  module  as  you  wish  by 
explicitly  declaring  them  (with  the  COMMON  statement  in  FORTRAN  or  the 
.PSECT  directive  ir.  MACRO-11,  for  example)  or  by  allowing  the  language 
translator  to  create  them.  If  you  do  not  explicitly  create  a  program 
section  in  your  source  code,  the  language  translator  you  are  working 
with  will  create  a  "blank"  program  section  within  each  module 
translated.  This  program  section  will  appear  on  your  listings  and 
maps  as  .  BLK. .  For  more  information  on  explicitly  declared  program 
sections,  s^e  your  language  reference  manual. 


A  program  section's  name  is  the  name  b 
and   TKB   reference   it.    When   proce 
translator  and  TKB  create  internal  tab 
names,   attributes,   and   lengths.    A 
declared  more  than  once.    However,   a 
program   section   must  have  identical 
more  than  once  in  the  same  module   or 
program   section.    Identically  named 
module  and  global  program  sections  wit 
to  declare  the  program  section  as  havi 
an  error.   However,  identically  named 
attributes   may   appear   in  different 
program  s.»ction8  have  the  local  (LCL) 


y  which  the  la 
ssing  files, 
les  that  conta 
named  progr 
11  occurrence 
attributes  if 

if  the  sect 
program  sectio 
h  differing  at 
ng  multiple  at 
program  sectio 
trees  of  an  ov 
attr  ibute . 


nguage  translator 
both  the  language 
in  program  section 
am  section  can  be 
s  of  that  named 
the  section  occurs 
ion  is  a  global 
ns  within  the  same 
tributes  cause  TKB 
tributes,  which  is 
..s  with  differing 
erlaid  task  if  the 
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Program  section  attributes  define  a  program  section's  contents,  its 
placement  in  a  task  image,  and,  in  some  cases,  the  allowed  mode  of 
access  (read/write  or  read-only). 

A  program  section's  length  determines  how  much  address  space  TKB  must 
reserve  for  it. 

When  a  program  consists  of  more  than  one  module,  it  is  not  unusual  for 
program  sections  of  the  same  name  to  exist  in  more  than  one  of  the 
modules.  Therefore,  as  TKB  scans  the  object  modules,  it  collects 
scattered  occurrences  of  program  sections  of  the  same  name  and 
combines  them  into  a  single  area  of  your  task  image  file.  The 
attributes  listed  in  Table  2-1  control  the  way  TKB  collects  and  places 
each  program  section  in  the  task  image. 

Table  2-1 
Program  Section  Attributes 

Attribute     Value  Meaning 

access-code      RW      Read/write:   data  can  be  read   from,   and 

written  into,  the  program  section. 

RO  Read-only:  data  can  be  read  from,  but 
cannot  be  written  into,  the  program 
section. 

allocation-code   CON     Concatenate:   all  references  to   a   given 

program  section  name  are  concatenated; 
the  total  allocatioi  is  the  sum  of  the 
individual  allocations. 

OVR     Overlay:    all   references   to   a  given 

program   section  name  overlay  each  other; 

the  total  allocation  is  the  length  of  the 
longest  individual  allocation. 

relocation-code   REL     Relocatable:   the  base   address  of   the 

program  section  is  relocated  relative  to 
the  base  address  of  the  task. 

ABS  Absoj-ute:  the  base  address  of  the 
program  section  is  not  relocated;  it  is 
always  0. 

save  SAV     The   program    section    has    the    SAVE 

attribute,  and  TKB  forces  the  program 
section  into  the  root. 

scope-code       GBL     Global:    the   program   section   name   is 

recognized  across  overlay  segment 
boundaries;  TKB  allocates  storage  for 
the  program  section  from  references 
outside  the  defining  overlay  segment. 

LCL  Local:  the  program  section  name  is 
recognized  only  within  the  defining 
overlay  osgment;  TKB  allocates  storage 
for  the  program  section  from  references 
within  the  defining  overlay  segment  only. 

(continued  on  next  page) 
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Table  2-1  (Cont.) 
Program  Section  Attributes 


Attribute      Value  Meaning 

type-code         D       Data:   the  program  section  contains  data. 

I  Instruction:  the  program  section 
contains  either  instructions,  or  data  and 
instructions . 


2.1.1.1  Access-code  and  Allocation-code  -  TKB  uses  a  program 
section's  access-code  and  allocation-code  to  determine  its  placement 
and  size  in  a  task  image.  If  you  specify  /SG  in  the  command  sequence, 
TKB  divides  address  space  into  read/write  and  read-only  areas,  and 
places  the  program  sections  in  the  appropriate  area  according  to 
access-code.  However,  the  default  is  to  order  the  program  sections 
alphabetically. 

TKB  uses  a  program  section's  allocation-code  to  determine  its  starting 
address  and  length.  If  a  program  section's  allocat ic n-code  indicates 
that  TKB  is  to  overlay  it  (OVR) ,  TKB  places  each  allocation  to  the 
program  section  from  each  module  at  the  same  address  within  the  task 
image.  TKB  determines  the  total  size  of  the  program  section  fi.om  the 
length  of  the  longest  allocation  to  it. 

If  a  program  section's  allocation-code  indicates  that  TKB  is  to 
concatenate  it  (CON),  TKB  places  the  allocation  from  the  modules  one 
after  the  other  n  the  task  image,  and  determines  the  total  allocation 
from  the  sum  ol    the  lengths  of  each  allocation. 

TKB  always  allocates  address  space  for  a  program  section  beginning  on 
a  word  boundary.  If  tl.e  program  section  has  the  D  (data)  and  CON 
(concatenate)  attributes,  TKB  appends  to  the  last  byte  of  the  previous 
allocation  all  storage  contributed  by  subsequent  modules.  It  does 
this  regardless  of  whether  that  byte  is  on  a  word  or  nonword  boundary. 
For  a  program  section  with  the  I  (instruction)  and  CON  attributes, 
however,  TKB  allocates  address  space  contributed  by  subsequent  modules 
beginning  with  the  nearest  following  word  boundary. 

For  example,  suppose  three  modules,  INI,  IN2,  and  IN3,  are  to  be  task 
built.  Table  2-2  lists  these  modules  with  the  program  sections  that 
each  contains  and  their  access  codes  and  allocation  codes. 

In  this  example,  the  program  section  named  B,  with  the   attribute  CON 

(concatenate),   occurs  twice.   Thus,  the  total  allocation  for  B  is  the 

sum  of  the  lengths  of  each  occurrence;   that  is,  100  +  120  =  220.  The 

program   section   named   A  also  occurs  twice.   However,  it  has  the  OVR 

(overlay)  attribute;  so  its  total  allocation  is  the  largest  of  the 
two  sizes,  or  300.  Table  2-3  lists  the  individual  program  section 
allocations . 
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Table  2-2 
Program  Sections  for  Modules  INI,  IN2,  and  IN3 


Program 

Section 

Access 

Allocat  ion 

Size 

File  Name 

Name 

Code 

Code 

(Octal) 

INI 

B 

RH 

CON 

100 

k 

m 

OVR 

300 

C 

m 

CON 

150 

IN2 

k 

m 

OVR 

250 

B< 

KM 

CON 

120 

IN3 

C 

RO 

CON 

50 

Table  2-3 
Individual  Program  Section  Allocations 


Program  Section 
Name 


Total 
Allocation 


B 
A 
C 


220 
300 
220 


TKB  then  groups  the  program  sections  according  to  their   access   codes 
and  alphabetizes  each  group,  as  shown  in  Figure  2-3. 


NOTE 

The  example  shown  in  Figure  2-3 
represents  the  Task  Builder's  allocation 
of  program  sections  if  the  /SG  or  /MO 
switches  are  used.  For  more 
information,  see  the  description  of  the 
/MU,  /SQ,  and  /SG  switches  in  Chapter 
10. 


C  (220) 

B  (220) 

A  (300) 

STACK 

HEADER 

READ-ONLY 
ACCESS 

READ/WRITE 
ACCESS 

TASK  MEMORY 


ZK-379-81 


Figure  2-3   Allocation  of  Task  Memory 
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The  save  attribute  (SAV)  is  useful  in  cases  where  the  information  in  a 
program  section  must  be  kept  available  to  all  task  segments.  The  SAV 
attribute  of  a  program  section  causes  TKB  to  force  the  program  section 
into  the  root  of  an  overlaid  task.  Therefore,  the  named  common  block 
in  the  FORTRAN  SAVE  statement  or  the  named  program  section  in  the 
MACRO-11  .PSECT  directive  specified  with  the  SAV  attribute  are  in  the 
root  of  the  task. 


2.1.1.2  Type-Code  and  Scope-Code  -  The  scope-code  is  meaningful  only 
when  you  define  an  overlay  structure  for  a  task.  The  scope-code  is 
described  in  Chapters  3  and  4  within  the  context  of  the  descriptions 
of  overlays.  {The  type-code  is  meaningful  in  the  context  of  program 
sections  within  an  I-  and  D-space  task,  as  described  in  Chapter  7.} 


2.1.2   Resolving  Global  Symbols 

TKB  resolves  references  to  global  symbols  across  module  boundaries  and 
any  references  (explicit  or  implicit)  to  the  system  library.  When  the 
language  translators  process  a  text  file,  they  assume  that  references 
to  global  symbols  within  the  file  are  defined  in  other,  separately 
assembled  or  compiled  modules.  As  TKB  links  the  relocatable  object 
modules,  it  creates  an  internal  table  of  the  global  symbols  it 
encounters  within  each  module.  If,  after  TKB  examines  and  links  all 
the  object  modules,  references  remain  to  symbols  that  have  not  been 
defined,  TKB  assumes  that  it  will  find  the  definition  for  the  symbols 
within  the  default  system  object  module  library  (LB: [ 1 , 1 ] SYSLIB.OLB) . 
If  undefined  symbols  still  remain  after  SYSLIB  is  examined,  TKB  flags 
the  symbols  as  undefined.  If  you  have  not  specified  an  output  map  in 
your  TKB  command  sequence,  TKB  reports  the  names  of  the  undefined 
symbols  to  you  on  your  terminal.  If  you  have  specified  an  output  map, 
TKB  outputs  to  your  terminal  only  the  fact  that  the  task  contains 
undefined  symbols.  The  names  of  the  symbols  appear  on  your  map 
1 isting . 

When  creating  the  task  image  file,  TKB  resolves  global  references,  as 
shown  in  the  following  example.  Table  2-4  lists  the  three  files  INI, 
IN2,  and  IN3,  showing  the  program  sections  within  each  file,  the 
global  symbol  definitions  within  each  program  section,  and  the 
references  to  global  symbols  in  each  program  section. 

Table  2-4 
Resolution  of  Global  Symbols  for  INI,  IN2,  and  IN3 

File     Program  Section      Global       Global 
Name         Name  Definition     Reference 


INI  B  Bl  A 

B2  LI 

A  CI 


XXX 


c 


IN2  A  A 

B  Bl  B2 

IN3  C  Bl 


2-7 


TASK  BUILDER  FONCTIONS 

In  processing  the  first  file,  INI,  TKB  finds  definitions  ror  81  and  B2 
and  references  to  A,  LI,  CI,  and  XXX.  Because  no  definition  exists 
for  these  references,  TKB  defers  the  resolution  of  these  global 
symbols.  In  processing  the  next  file,  IN2,  TKB  finds  a  definition  for 
A,  which  resolves  the  previous  reference,  and  a  reference  to  B2 ,  which 
can  be  immediately  resolved. 

When  all  the  object  files  have  been  processed,  TKB  has  three 
unresolved  global  reference:  CI,  LI,  and  XXX.  Assume  that  a  search 
of  the  system  library  LB: [ 1 , 1] SYSLIB .OLB  resolves  LI  and  XXX,  and  TKB 
includes  the  defining  modules  in  the  task's  image.  Assume  also  that 
TKB  cannot  resolve  the  global  symbol  CI.  TKB  lists  it  as  an  undefined 
global  symbol . 

The  relocatable  global  symbol  Bl  is  defined  twice.  TKB  lists  it  as  a 
multiply  defined  global  symbol.  TKB  uses  the  first  definition  of  that 
multiply  defined  symbol. 

Finally,  an  absolute  global  symbol  (for  example,  symbol=100)  can  be 
defined  more  than  once  without  being  listed  as  multiply  defined,  as 
long  as  each  occurrence  of  the  symbol  has  the  same  value. 


2.2   THE  TASK  STRDCTORE 

TKB  builds  the  data  structures  required  by  other  system  programs  and 
incorporates  them  into  the  task  image.  The  Executive  (which  is 
responsible  for  the  allocation  of  system  resources)  must  have  access 
to  the  data  for  all  tasks  on  the  system.  It  must  know,  for  example,  a 
task's  size  and  priority,  and  it  must  have  information  about  the  way 
each  task  expects  to  use  the  system.  It  is  the  Task  Builder's 
responsibility  to  allocate  space  in  the  task  image  for  the  data 
structures  required  by  the  Executive.  For  example,  TKB  allocates 
space  for  the  task  header  and  initializes  it. 

The  disk  image  file  created  by  TKB  contains  the  linked  task  and  all  of 
the  information  required  by  the  system  programs  to  install  and  run  it. 
In  its  simplest  form,  the  disk  image  file  consists  of  three  physically 
contiguous  parts: 

•  The  label  block  group 

•  The  task  header 

•  The  task  memory  image 

Figure  2-4  illustrates  the  basic  simplified  structure  of  this  file. 

The  label  block  group  contains  data  produced  by  TKB  and  used  by 
INSTALL  command  processing.  It  contains  information  about  the  task, 
such  as  the  task's  name,  the  partition  in  which  it  runs,  its  size  and 
priority,  and  the  logical  units  assigned  to  it.  When  you  install  the 
task,  INSTALL  command  processing  (hereinafter  called  INSTALL)  uses 
this  information  to  create  a  Task  Control  Block  (TCB)  entry  for  the 
task  in  the  System  Task  Directory  (STD)  and  to  initialize  the  task's 
header  information. 

The  task's  header  contains  information  that  the  Executive  uses  when  it 
runs  the  task.  The  header  also  provides  a  storage  area  for  saving  the 
task's  essential  data  when  the  task  is  checkpointed .  TKB  creates  and 
partially  initializes  the  header;  INSTALL  initializes  the  rest  of  the 
header  . 
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TASK 
MEMORY 


HEADER 


LABEL 
BLOCK 


Figure  2-4   Disk  Image  of  the  Task 

The  task  memory  contains  the  linked  modules  of  the  program  and, 
therefore,  the  code  and  data.  It  also  contains  the  task's  stack.  The 
stack  is  an  area  of  task  memory  that  a  task  can  use  for  temporary 
storage  and  subroutine  linkage.  It  can  be  referenced  through  general 
register  6,  the  stack  pointer  (SP) .  The  label  block  group,  the  task's 
header,  and  the  task  memory  are  described  in  detail  in  Appendix  B. 

The  task's  memory  image  is  the  part  of  your  task  that  the  system  reads 
into  physical  memory  at  run  time.  The  label  block  group  is  not 
required  in  physical  memory.  Therefore,  in  its  simplest  form,  the 
task's  memory  image  consists  of  only  two  parts:  the  task  header  and 
task  memory.   Figure  2-5  shows  the  memory  image. 


TASK 
:  MEMORY  : 


HEADER 


ZK  3«i-8i 


Figure  2-5   Memory  Image 
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2.3   OVERLAYS 

This  section  is  an  introduction  to  overlaid  tasks.  Details  about 
overlaid  tasks  can  be  found  in  Chapter--  3  and  4. 

Using  overlays  can  save  memory  space  by  reducing  the  size  of  the 
executing  portion  of  the  task  or  the  physical  memory  required  by  the 
task.  Parts  of  an  overlaid  task  reside  on  disk,  thereby  saving  memory 
space. 

An  overlaid  task  is  a  task  de5;igned  to  have  discrete  parts.  The  parts 
of  a  task  designed  this  way  can  execute  relatively  independently  of 
other  parts.  Parts  of  an  overlaid  tasK  reside  on  disk  until  they  are 
needed  for  their  required  function.  The  common  part  of  the  task, 
which  stays  in  memory,  is  the  root.  The  root  calls  the  other  parts  of 
the  task,  which  are  referred  to  as  segments,  from  disk  into  memory. 

The  RSX-IIM/M-PLUS  systems  have  two  types  of  overlaid  tasks.  One  type 
of  overlaid  task  reads  in  segments  from  disk  over  other  segments 
already  in  memory.  A  task  of  this  type  is  called  a  d isK- resident 
overlaid  task.  In  this  task,  segments  reside  on  disk  until  they  are 
needed.  The  segments  in  disk-resident  overlays  that  share  the  same 
memory  address  space  of  the  task  with  other  segments  must  be  logically 
independent  of  those  segments.  The  independence  is  necessary  because 
the  other  segments  are  on  disk  and  cannot  be  referenced.  For  example. 
Task  A,  an  overlaid  task  root,  can  call  either  of  two 
segments:  segment  B  or  segment  C.  The  root  of  Task  A  initially  calls 
segment  B.  Segr-^nts  B  and  C  occupy  the  same  memory  space.  Segment  B 
cannot  call  segment  C  and  segment  C  cannot  call  segment  B.  However, 
if  segment  B  returns  control  of  the  task  to  the  root  of  task  A,  the 
root  can  then  call  segment  C.  Segment  C  would  then  be  read  into 
memory  over  segment  B.   Figure  2-6  illustrates  this  sequence. 

Because  segments  of  a  disk-resident  overlaid  task  can  occupy  the  same 
memory  space,  a  disk-overlaid  task  can  occupy  less  memory  than  it 
would  if  it  were  not  overlaid.  However,  more  disk  I/O  transfers  (and, 
therefore,  more  time)  are  needed  for  this  type  of  task. 

Another  type  of  overlaid  task  is  the  memory-resident  overlaid  task. 
In  this  task,  the  segments  reside  on  disk  until  they  are  needed.  At 
tnat  time,  the  needed  S'3gment  is  read  into  a  sequentially  adjacent 
area  of  memory  and  resides  there  until  the  task  ends.  For  example,  a 
memory-resident  overlaid  Task  A  has  two  segments:  segment  B  and 
segment  C.  If  the  root  of  task  A  calls  segment  B,  segment  B  is  read 
into  memory  adjacent  to  the  root.  When  the  root  regains  control  and 
then  calls  segment  C,  segment  r  is  read  into  memoiy  adjacent  to 
segment  B.   Figure  2-7  illustrates  this  sequence. 

Memory-resident  overlaid  tasks  execute  faster  than  disk-resident 
overlaid  tasks.  The  increase  in  speed  occurs  because  fewei  disk  I/O 
transfers  are  needed  during  task  execution. 


• 
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Figure  2-6   Simple  2-Segment,  Disk-Resident  Overlay  Galling  Sequence 
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Figure  2-7   Simple  2-Segment ,  Memory-Resident  Overlay  Calling 
Sequence 
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2.4   ADDRESSING  CONCEPTS 

The  primary  addressing  mechanism  of  the  PDP-11  is  the  16-bit  computer 
word.  The  maximum  physical  address  space  that  the  PDP-11  can 
reference  at  any  one  time  is  a  function  of  the  length  of  this  word. 
Because  of  the  16-bit  word  size,  a  task  can  have  an  address  no  larger 
than  177777 (octal)  (32K  words)  within  the  task  image  for  nonpr i v i leged 
tasks  on  an  unmapped  system.  In  practice,  the  task  size  may  be 
limited  to  a  few  words  less  than  32K  because  of  system  design. 


2.4.1   Physical,  Virtual,  and  Logical  Addresses 

Physical,  virtual,  and  logical  addresses,  and  virtual  and  logical 
address  space,  are  concepts  that  provide  a  basis  for  understanding  the 
functions  of  task  addressing  and  the  use  of  task  windows, 

-  A  single,  physical  location  in  memory   is 
-^-^ress  . 


Physical  addresses  -  A 
called  the  physical  add 


Memory  is  divided  into  parts  called  bytes.  They  are  numbered 
according  to  their  position  in  memory.  Therefore,  the  lowest 
byte  is  0  and  the  highest  byte  is  whatever  the  upper  limit  of 
memory  may  be  for  a  particular  system;  for  example,  32K,  64K, 
and  so  forLh.  The  assigned  number  is  called  the  physical 
address . 

A  task  contains  addresses  (for  example,  0  through  2200).  TKB 
relocates  the  task's  addresses  in  an  unmapped  system  by  a 
number  represented  by  the  base  c.ddress  of  the  partition  in 
which  it  is  installed.  After  installation,  the  task's 
addresses  refer  to  physical  addresses  of  memory,  which  always 
correspond  to  the  same  physical  memory  in  an  unmapped  system. 

Therefore,  the  task  addresses  have  an  actual  one-to-one 
relationship  to  physical  memory.  The  same  relationship  exists 
any  time  the  task  is  in  memory.  The  memory  (physical) 
addresses  will  not  be  from  0  through  2200.  For  example,  after 
the  task  is  installed  in  the  partition,  the  task's  address  of 
0  may  become  physical  address  17000  because  the  Task  Builder 
added  in  the  offset,  which  is  equal  to  the  partition  base 
address . 

In  a  mapped  system,  the  task's  addresses  remain  the  same  but 
the  physical  memory  addresses  may  change  due  to  Executive 
processes  (checkpointing,  swapping,  and  so  forth.). 
Therefore,  the  task  iddresses  do  not  always  correspond  to  the 
same  physical  memory.  If  the  task  uses  memory  management 
directives,  the  memory  addressing  can  be  changed  by  the  task 
to  include  any  part  of  physica)  memory  that  it  is  allowed  to 
access. 

Virtual  addresses  -  A  task's  virtual  addresses  are  the 
addresses  within  the  task. 

The  PDP-11 's  16-bit  word  length  (a  mapped  system)  imposes  the 
address  range  of  32K  words  on  the  virtual  addresses. 
Therefore,  these  task  addresses  could  include  addresses  0 
through  177777 (octal)  depending  on  the  length  of  the  task. 
These  task  addresses  are  not  the  same  as  the  actual  addresses 
of  the  memory  in  which  the  task  resides. 
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•  Virtual  address  space  -  A  task's  virtual  address  space  is  that 
space  encompassed  by  the  range  of  virtual  addresses  that  the 
task  uses. 

With  the  Create  Address  Window  (CRAW$)  memory  management 
directive,  a  task  can  divide  its  virtual  address  space  into 
segments  called  virtual  address  windows.  By  using  address 
windows,  you  can  manipulate  the  mapping  of  virtual  addresses 
to  different  areas  of  physical  memory. 

•  Logical  addresses  -  A  task's  logical  addresses  are  the  actual 
physical  memory  addresses  that  the  task  can  access, 

•  Logical  address  space  -  The  task's  logical  address  space  is 
the  total  amount  of  physical  memory  to  which  the  task  has 
access  rights. 

The  physical  memory  represented  by  the  logical   addresses   may 

or   may   not  be  continuous.   The  items  in  physical  memory  that 

logical  address  space  includes  are  the  task  itself,  and  static 
and  dynamic  regions. 


2.4.2   Unmapped  Systems 

In  an  unmapped  system,  the  task's  virtual  address  space  and  its 
logical  address  space  coincide  exactly,  as  shown  in  Fi9ure  2-8. 

In  an  unmapped  system,  the  task's  address  space  is  limited  to  32K 
words.  All  of  the  machine's  physical  memory  and  all  of  its  device 
registers  are  accessible  to  all  tasks  running  on  the  system.  The  top 
4K  words  of  address  space  are  reserved  for  the  UNIBUS  addresses  that 
correspond  to  the  peripheral  device  registers  (the  I/O  page),  and  a 
segment  of  low  memory  is  occupied  by  the  Executive.  Therefore,  in  an 
unmapped  system,  the  largest  task  size  is  32K  words  minus  the  I/O  page 
and  the  size  of  the  Executive.  Figure  2-9  shows  the  memory  layout  for 
an  unmapped  system. 

Unmapped  systems  contain  only  user-controlled  partitions.  When  TKB 
links  the  relocatable  object  modules  of  a  task  that  is  to  run  on  an 
unmapped  system,  it  requires  that  you  specify  the  partition  in  which 
the  task  is  to  run,  and  the  partition's  base  address  and  length.  TKB 
sets  the  base  address  of  the  task  to  the  base  address  of  the 
partition.  This  means  that  the  task's  location  in  physical  memory  is 
bound  to  the  partition  and  does  not  change.  Because  all  of  physical 
memory  in  an  unmapped  system  is  directly  addressable,  and  the  task's 
location  within  memory  does  not  change,  the  addresses  that  TKB  assigns 
coincide  exactly  with  the  physical  addresses  of  the  machine  and, 
therefore,  do  not  need  to  be  relocated  at  run  time. 


2.4.3   Mapped  Systems 

A  mapped  system  is  one  in  which  the  processor  contains  a  KT-11  memory 
management  unit.  The  processor  handbook  for  your  machine  contains  a 
complete  description  of  the  memory  management  unit. 

Mapped  processors  have  up  to  three  mooes  of  operation:  kernel, 
supervisor,  and  user  (th«  PDP-11/34  does  not  have  supervisor  mode). 
The  information  in  this  section  is  relevant  to  user  mode  only. 
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Figure  2-8   Virtual  and  Logical  Address 
in  an  Unmapped  System 
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Space  Coincidence 


In  a  mapped  system,  the  relationship  between  virtual  address  space  and 
physical  address  space  i?  different  from  that  of  an  unmapped  system. 
The  primary  addressing  mechanism  for  a  mapped  system  is  still  the 
16-bit  word,  and  virtual  address  space  is  still  32K  words.  However,  a 
mapped  system  has  a  much  greater  physical  memory  capacity  and, 
therefore,  physical  memory  and  virtual  address  space  do  not  coincide. 
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32  K  WORDS 


•  EXECUTIVE* 


Figure  2-9   Memory  Layout  for  Unmapped  System 


The  memo'-y  management  unit  divides  a  machine's  32K 
address  space  into  eight  4K-word  segments  or  pages, 
registers  associated  with  it: 


words   of   virtual 
Each  page  has  two 


•  A  16-bit  Page  Description  Register  (PDR),  which  contains 
control  and  access  information  about  the  page  with  which  it  is 
associated 


•   A  16-bit  Page  Address  Register 
relocation  register 


(PAR),   which   is   an   address 


The  PDRs  and 
Active  Page 
management  unit 


PARS  are  always  used  as  a  pair.   Fach  pair  is   called   an 
Register   (APR).    Figure   2-11   shows   how   the   memory 
divides  the  32K  words  of  virtual  address  space. 


The  Executive  allocates  only  as  many  APRs  as  are  necessary  to  map  a 
given  task  into  physical  meiiory.  Therefore,  a  4K-word  task  requires 
one  APR;  a  6K-word  task  requires  two.  Figure  2-12  illustrates  this 
mapping . 
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Figure  2-11   Memory  Management  Unit's  Division  of  Virtual 

Address  Space 
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2.4.4   Regions 

This  section  briefly  describes  regions  and  their  relationship  to  and 
use  by  tasks.  Regions  and  their  use  are  more  thoroughly  described  in 
Chapter  5. 

A  region  is  a  defined  area  of  memory  that  can  contain  code  or  data. 
It  can  also  be  a  blank  area  reserved  for  use  by  one  or  more  tasks. 
The  region  is  named  and  built  like  a  task  except  that  the  /HD  header 
switch  is  negated  (/-HD)  because  the  region  is  not  a  task  and  does  no*- 
need  a  task  header.  Tasks  can  also  create  '-egions  dynamically  as  they 
execute.  Dynamic  regions  are  useful  because  they  increase  the  task's 
logical  address  space  while  saving  its  virtual  address  space.  Regions 
also  allow  tasks  to  share  code  and  data  with  other  tasks. 
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Figure  2-12   Mapping  for  4K-Word  and  6K-Word  Tasks 


Regions  are  named  according  to  their  use  or  the  way  in  which  they  were 
built.   Theso  regi^.is  are: 

•  Task  Region  --  A  continuous  block  of  memory  in  which  the  task 
runs . 

•  Common  Shared  Region  —  On  unm-pped  systems,  a  shared  region 
defined  by  an  operator  at  run  time  or  built  into  the  system 
during  system  generation;   for  example,  a  global  common  area. 
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Resident  commons  are  usually  called  shareil  regions  because 
they  are  used  as  an  area  in  which  tasks  share  common  data. 
Shared  regions  can  be  absolute  or  position  independent. 
Shared  regions  and  their  use  are  described  in  Chapter  5. 

•  Library  Shared  Region  --  A  shared  region  containing  common 
code  or  routines  shared  by  tasks,  and  in  this  way  saving 
virtual  address  space  in  the  tasks. 

•  Dynamic  Kegion  --  A  region  created  dynamically  at  run  time  by 
the  Create  Region  (CRRG$)  memory  management  directive  in  the 
task.  This  directive  and  associated  directives  are  described 
in  the  RSX-llM/M-PLUS  Executive  Reference  Manual. 

By  convention,  a  shared  region  that  contains  code  is  a  library  and  a 
shared  region  that  contains  data  is  a  common. 

Tasks  must  map  to  a  region  by  using  task  windows  which  must  be  defined 
and  numbercu  in  the  task  when  the  task  is  built.  Usually,  a  task  uses 
one  window  for  each  region  to  which  mapping  must  occur.  Task  windows 
are  described  in  the  next  section,  Task  Mapping  and  Windows. 

Figure  2-14  shows  a  sample  collection  of  regions  that  could  make  up  a 
task's  logical  address  space.  A  task's  logical  address  space  can 
expand  and  contract  dynamically  as  the  task  issues  the  appropriate 
memory  management  directives.  The  header  and  root  senment  are  always 
part  of  the  region.  Therefore,  the  task  header  and  root  segment 
always  use  window  0  (UAPR  0)  and  region  0.  Because  a  region  occupies 
3  continuous  area  of  memory,  each  region  is  shown  as  a  separate  block. 


2.5   TASK  MAPPING  AND  WINDOWS 

As  mentioned  earlier,  tasks  that  run  on  mapped  systems  must  be 
relocated  at  run  time.  When  you  build  a  task  that  is  to  run  on  a 
mapped  system,  TKB  creates  and  places  in  the  header  of  the  task  one  or 
more  8-word  data  structures  called  window  blocks.  When  you  install  a 
task,  INSTALL  initializes  the  window  block(s).  Once  initialized,  a 
window  block  describes  a  range  of  continuous  virtual  addresses  called 
a  window. 


2.5.1   Task  Windows 

A  window  can  be  as  small  as  32  words  or  as  large  as  32K  words.  When  a 
task  consists  of  one  continuous  range  of  addresses  (a  single  region 
task)  only  one  window  block  is  required  to  describe  the  entire  task 
from  the  beginning  of  its  header  to  the  highest  virtual  address  in  the 
task.  Wh^n  a  task  consists  of  two  or  more  regions  (such  as  a  task 
that  references  a  shared  region  as  described  in  Chapter  5),  each 
region  must  have  at  least  one  window  block  associated  with  it  that 
describes  all  or  a  portion  of  the  region. 

When  the  Executive  maps  a  task  into  physical  memory,  it  extracts  the 
information  it  requires  to  set  up  the  APRs  of  the  memory  management 
unit  from  the  task's  window  block. 
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In  an  RSX-IIM  system,  regardless  of  the  number  of  regions  associated 
with  a  task,  the  region  that  contains  the  task's  header  and  root  is 
always  described  by  window  0.  Windows  0  and  1  describe  the  root  of  an 
I-  and  D-space  task  in  an  RSX-llM-PLUS  system.  Window  0  describes  the 
I-space  root  and  window  1  describes  the  D-space  root  and  task  header. 
Furthermore,  this  region  is  referred  to  as  the  task  region  and  is 
identified  as  region  0.  Figure  2-13  illustrates  window  block  0  for  a 
system  without  I-  and  D-space.  Windows  for  an  I-  and  D-space  task  are 
described  in  Chapter  7. 
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Figure  2-13   Window  Block  0 


When  you  run  your  task,  the  Executive  determines  where  in  physical 
memory  the  task  is  to  reside.  The  Executive  then  loads  the  Page 
Addresj  Register  portion  of  the  APRs  with  a  relocation  constant  that, 
when  combined  with  the  addresses  of  the  task,  yields  the  18-  or  22-bit 
physical  address  range  of  the  task. 

Referring  to  Figure  2-14,  which  illustrates  a  mapped  system  without  I- 
and  D-space,  you  can  observe  that  a  large  32K  user  task  contains  three 
distinct  areas  of  continuous  space  called  "windows."  The  term  "task 
window"  is  a  construct  that  maps  a  continuous  portion  of  the  task's 
virtual  address  space  to  a  continuous  portion  of  a  region  in  the 
task's  logical  address  space.  Windows  must  have  a  specified  size  and 
starting  address.   The  window  size  can  be  from  32  words  to   32K   minus 
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32  words,  and  windows  must  start  on  a  4K  address  boundary.  Figure 
2-14  shows  three  windows  that  are  not  continuous  in  the  task's  virtual 
address  space.  However,  the  space  within  each  window  is  continuous. 
In  this  task,  the  size  of  window  0  is  IIK;  the  size  of  window  1  is 
IIK;  and  the  size  of  window  2  is  8K.  The  concept  of  windows  exists 
for  the  following  specific  reason. 

By  using  the  concept  of  windows  and  the  memory  management  directives, 
a  nonpr iv i leged  task  can  access  a  larger  logical  memory  space  than 
that  implied  by  the  32K  virtual  addressing  range  and  normally 
accessible  by  the  16-bit  address.  A  task  can,  in  fact,  only  access 
J2K  of  memory  at  one  time.  However,  a  nonpr iviloged  task  can  change 
its  access  to  logical  addresses  (real,  physical  memory).  The  area 
that  your  program  accesses  can  be  changed  by  the  program  during 
program  execution.  The  process  of  accessing  different  logical  areas 
of  memory  is  called  "mapping." 

By  referring  to  Figure  2-14,  you  can  see  that  window  1  i-»  the  task  is 
mapped  to  region  1  in  physical  memory.  The  task  can  change  the  window 
1  mapping  to  region  0  in  physical  memory.  In  effect,  then,  though  a 
task  is  limited  to  a  range  of  32K  virtual  addresses,  a  task  can  access 
all  the  physical  memory  available  to  it  (determined  by  the  way  that 
you  set  up  the  mapping)  by  changing  the  mapping  of  its  windows  to 
different  logical  addresses.  Figure  2-14  ptovides  a  visual 
description  of  the  concept  of  mapping  to  different  logical  addresses. 

The  discussion  now  proceeds  to  setting  up  the  task's  windows.  This  is 
done  by  defining  task  window  blocks  to  TKB. 

To  manipulate  virtual  address  mapping  to  various  logical  areas,  you 
must  first  divide  a  task's  32K  of  virtual  address  space  into  segments. 
These  segments  are  task  (virtual  address)  windows.  Each  window 
encompasses  a  continuous  range  of  virtual  addresses.  The  first 
address  of  the  window  address  range  must  be  a  multiple  of  4K  (the 
first  address  must  begin  on  a  4K  boundary)  because  of  the  way  that  the 
KT-11  memory  management  unit  uses  APRs . 

On  an  RSX-llM  system,  you  can  specify  up  to  seven  windows.  Task 
mapping  for  the  task's  code  requires  the  use  of  window  0.  Therefore, 
there  is  a  total  of  eight  windows.  However,  window  0  Is  not  available 
to  nonpr ivileged  tasks.  The  size  of  each  window  can  range  from  a 
minimum  of  32  words  to  a  maximum  of  32K  minus  32  words. 

RSX-llM-PLUS  tasks  that  use  I-  and  D-space  or  oupervisor-mod* 
libraries  have  a  total  of  16  windows.  you  can  specify  up  to  14 
windows  In  this  type  of  task.  Windows  0  and  1  are  not  available  to 
nonprivileged  tasks  in  this  kind  of  system. 

A  task  that  includes  directives  that  dynamically  manipulate  address 
windows  must  have  task  window  blocks  set  up  in  the  task  header  as  well 
as  Window  Definition  Blocks  in  the  code  for  use  by  the  Create  Address 
Window  directive.  The  Executive  uses  task  window  blocks  to  identify 
and  describe  each  currently  existing  window.  When  linking  the  task, 
the  programmer  specifies  the  number  of  extra  window  blocks  needed  by 
the  task.  The  number  of  blocks  should  equal  the  maximum  number  of 
windows  that  will  exist  concurrently  while  the  task  is  running. 
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In  RSX-llM  or  RSX-ilM-PLUS  without  I-  and  D-space,  a  window's 
identification  is  a  numbpr  from  0  to  7,  which  is  an  index  to  the 
window's  corresponding  window  block.  The  address  window  identified  by 
0  is  the  window  that  always  maps  the  task's  header  and  root  segment. 
TKB  creates  window  0,  which  the  Executive  uses  to  map  the  task.  No 
directive  may  specify  window  0;   a  directive  that  does  so  is  rejected. 

In  an  RSX-llM-PLUS  system  using  an  I-  and  D-space  task,  a  window's 
identification  is  a  number  from  0  to  15,  which  is  an  index  to  the 
window's  corresponding  window  block.  The  address  windows  identified 
by  0  and  1  arp  the  windows  that  always  map  the  task's  header  and  root. 
TKB  creates  windows  0  and  1,  which  the  Executive  uses  to  map  the  task. 
No  diro'"*-vve  may  specify  windows  0  or  1;  a  directive  that  does  so  is 
rejecte 

When  a  task  uses  memory  management  directives,  the  Executive  views  the 
relationship  between  the  task's  virtual  and  logical  address  space  in 
terms  of  windows  and  regions.  Unless  a  virtual  address  is  part  of  an 
existing  address  window,  the  address  does  not  point  anywhere.  This  is 
a  point  to  watch  when  setting  up  windows  with  the  Create  Address 
Window  directive  (CRAWS).  Similarly,  a  window  can  be  mapped  only  to 
an  area  that  is  all  or  part  of  an  existing  region  within  the  task's 
logical  address  space. 

Once  a  task  has  defined  the  necessary  windows  and  regions,  the  task 
can  issue  memory  management  directives  to  perform  operations  such  as 
the  following : 

•  Map  a  window  to  all  or  part  of  a  region. 

•  Unmap  a  window  from  one  region  in  order  to  map  it   to   another 
reg  ion . 

•  Unmap  a  window  from  one  part  of  a  region  in  order  to  map  it  to 
another  part  of  the  same  region. 


2.6   RSX-llM-PLUS  SUPERVISOR  MODE 

Three  modes  of  operation  are  possible  in  the  PDP-11:  user  mode, 
supervisor  mode,  and  kernel  mode.  Each  mode  has  associated  with  it  16 
APRS  for  mapping  memory:  8  I-space  APRs  and  8  D-space  APRs .  A  task 
in  the  RSX-llM-PLUS  system  can  use  supervisor-mode  libraries  and 
thereby  double  the  task's  virtual  address  space  •"O  64K  words. 
Supervisor-mode  libraries  are  described  in  Chapter  8.  This  section 
briefly  describes  supervisor  mode  and  the  mapping  that  occurs  when  the 
task  uses  supervisor  mode. 

Supervisor-mode  libraries  are  libraries  of  routines  that  are  used  only 
in  supervisor  r.iode.  The  task  switches  to  supervisor  mode  when  it 
calls  a  routine  within  the  supervisor-mode  library.  By  using  a 
supervisor  mode  libr  ry  as  described  in  Chapter  8,  you  make  the 
RSX-llM-PLUS  system,  for  large  systems,  us^  the  supervisor-Mode  APRs. 


2.6.1   Supervisor-Mode  Mapplntj 

Normally,  a  task  has  an  address  space  of  32K-words  by  using  eight  user 
APRs.  When  a  conventional  task  links  to  a  supervisor-mode  library  and 
calls  a  routine  in  the  library,  the  Executive  copies  the  user-mode 
I-space  APRs  into  the  supervisor-mode  D-space  APRs  and  maps  the 
supervisor-mode  library  with  supervisor  I-space  APRs.  Therefore, 
while  in  supervisor  mode  and  within  the  library,  the  task  can  access 
32K-words  ol  its  own  space  with  D-space  APRs  and  32K-word3  of   library 
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The  mapping  of  a   conventional   task   in   a   system 
supervisor-mode  library  is  shown  in  Figure  2-15. 

The  mapping   of   a   conventional   task   in   a   system 
supervisor-mode  library  is  shown  in  Figure  2-16. 
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2.7   PRIVILEGED  TASKS 

RSX-llM/M-PLUS  systems  have  two  classes  of  tasks:  privileged  and 
nonpr ivi leged .  However,  the  term  "privileged"  has  meaning  in  mapped 
systems  only,  because  in  mapped  systems  certain  areas  of  memory  are 
protected  from  nonpr ivi leged  tasks.  In  an  unmapped  system,  any  task 
has  the  ability  to  access  all  of  physical  memory  if  bO  programmed. 
Therefore,  the  distinction  between  these  two  classes  of  tasks  is 
primarily  one  of  their  mapping  to  memory  in  a  mapped  system. 

Privileged  tasks  in  a  mapped  system  can  access  system  data  areas  and 
the  Executive.  Altering  system  data  areas  or  the  Executive  can  cause 
obscure  and  difficult  problems.  Therefore,  privileged  tasks  must  be 
programmed  and  used  with  all  caution. 

You  can  specify  a  task  as  privileged  by  using  the  /PR  switch  in  the 
TKB  command  line.  The  /PR:0  switch  allows  a  task  to  perform  certain 
privileged  operations;  but,  the  /PR:0  task  cannot  access  the 
Executive  or  system  data  structures.  The  /PR:4  switch  allows  the  task 
to  directly  map  the  I/O  page.  Executive  routines,  and  system  data 
structures.  The  /PR:4  switch  is  used  for  a  privileged  task  in  a 
system  that  has  an  Executive  of  16K  or  less.  The  /PR:5  switch  allows 
a  task  to  directly  map  to  the  I/'O  page.  Executive  routines,  and  system 
data  structures.  The  /PR:5  switch  is  used  for  a  privileged  task  in  a 
system  that  has  an  Executive  of  20K  or  less. 

Chapter  6  describes  privileged  tasks  and  their  mapping  in  detail. 
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Figure   2-15      Mapping    foe   a   Conventional    User    Task   and   a   System 
Containing   a   Supervisor-Mode   Library   in   an   RSX-llM-PLUS  System 
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Figure    2-16      Mapping   for    a  Conventional    User    Task 
Using   a   Supervisor-Mode   Library   in   an   RSX-llM-PLUS   System 
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2.8   NULTIOSER  TASKS  (RSX-llM-PLOS  ONLY) 

The  following  section  is  an  introduction  to  multiuser  tasks,  whi'^h  are 
fully  described  in  Chapter  9. 

TKB  allows  you  to  build  multiuser  tasks.  A  multiuser  task  is  that 
which  has  one  portion  of  its  code  and  data  designated  as  read-only  and 
another  portion  designated  as  read/writ*?.  You  specify  the  read-only 
portions  of  your  task  with  program  sections  that  have  the  read-only 
access  code.  When  you  then  build  your  task  with  the  /MU  switch,  TKB 
places  the  read-only  portions  in  a  region  that  has  a  high  virtual 
address  and  the  read/write  portion  in  a  region  that  has  a  low  virtual 
address.  Any  other  requests  to  run  the  task,  if  the  task  is  already 
running,  results  in  a  copy  of  the  read/write  portion  of  the  task  in 
physical  memory  for  the  other  user.  There  is  always  only  one  copy  of 
the  read-only  code  regardless  of  the  number  of  tasks  that  may  be 
running. 

The  /MU  switch  is  described  in  Chapter  10. 


2.9   OSER-MODE  I-  AND  D-SPACE  TASKS  (RSX-llM-PLOS) 

User  tasks  that  use  both  I-  and  D-space  differ  from  conventional  tasks 
because  I-  and  D-space  tasks  have  specifically  defined  locations 
within  the  task  for  both  instructions  and  data.  Because  of  this 
separation,  the  I-  and  D-space  task  image  is  structurally  different. 

Additionally,  the  separate  instruction  areas  are  mapped  through 
separate  APRs  in  the  memory  management  unit.  Hence,  up  to  8  user-moae 
'nstruction  APRs  map  the  task's  instructions,  and  up  to  8  user-mode 
data  APRS  map  the  task's  data. 

Also,  overlaid  I-  and  D-space  tasks  are  more  complex  because  each 
overlaid  part  (segment)  of  such  a  task  may  reside  in  both  instruction 
space  and  data  space. 

I-  and  D-space  tasks  differ  from  conventional  tasks  in  the  following 
major  ways: 

•  PSECTs  with  the  "I"  attribute  contain  only  instructions  and 
PSECTs  with  the  "D"  attribute  contain  only  data. 

•  Two  sets  of  APRS  map  the  I-  and  D-space  task:  the  I-space 
APRS  and  the  D-space  APRs. 

•  I-  and  D-space  tasks  can  use  up  to  64K  words  of  virtual  space 
instead  of  32K  words  ecause  of  their  use  of  the  two  sets  of 
APRS.  With  supervisor-mode  libraries,  an  I-  and  D-space  task 
can  use  up  to  96K  words  of  virtual  space. 

The  following  have  data  contiguously  adjacent  in  memory,  and 
instructions  contiguously  adjacent  in  memory: 

•  Non-overlaid  I-  and  D-space  tasks 

•  Segments  in  an  overlaid  I-  and  D-space  task  that  contain  both 
I-  and  D-space 
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In  these  tasks  or  task  segments,  I-space  PSECTs   ace   segregated   from 
D-space  PSECTs  in  memory;   they  cannot  be  intermixed. 

Figure  2-17  shows  a  user-mode  I-  and  D-space  task  with  data   separated 
from  the  instruct  ons  and  mapped  to  memory  through  two  sets  of  APRs . 


TASK 

VIRTUAL 

ADDRESS 

SPACE 


USER-MODE 
APRS 


MEMORY 


DATA 


INSTRUCTIONS 


I-SPACE 


Figure  2-17:   Simplified  APR  Mapping  for  an  I-  and  D-space  Task 

I-  and  D-space  tasks  are  more  fully  described  in  Chapter  7.  The  task 
images  for  both  conventional  and  I-  and  D-space  tasks  are  described  in 
Appendix  B. 
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3.1   OVERLAY  STRUCTURES 

To  create  an  overlay  structure,  you  divide 
segments  consisting  of: 


task   into 


ser les 


of 


•  A  single  root  segment,  which  is  always  in  memory 

•  Any  number  of  overlay  segments,  you  must  consider  which  either 
1)  reside  on  disk  and  share  virtual  address  space  and  physical 
memory  with  one  another  (disk-resident  overlays);  or  2) 
reside  in  memory  and  share  only  virtual  address  space  with  one 
another  (memory-resident  overlays) 1 

Segments  consist  of  one  or  more  object  modules,  which  in  turn  consist 
of  one  or  more  program  sections.  Segments  that  overlay  each  other 
must  be  logically  independent;  that  is,  the  components  of  one  segment 
cannot  r>.ference  the  components  of  another  segment  with  which  it 
shares  virtual  addre  s  space.  In  addition  to  the  logical  independence 
of  the  overlay  segments,  you  nrust  consider  the  general  flow  of  control 
within  the  task  when  creating  overlay  segments. 

You  must  also  consider  the  kind  of  overlay  segment  to  create  at  a 
given   position  in  the  structure,  and  how  to  construct  it.   Dividing  a 


task  into  disk-resident  overlays  saves  physical  space,  

the  overhead  activity  of  loading  these  segments  each  time  they  are 
needed  --  but  are  not  present  --  in  memory.  Memory-resident 
overlays,  on  the  other  hand,  are  loaded  from  disk  only  the  first  time 
they  are  referenced.  Thereafter,  they  remain  in  memory  and  are 
referenced  by  remapping. 


1.  Note  that  memory-resident  overlays  can  be  used  only  if  the  hardware 
has  a  memory  management  unit,  and  if  support  for  the  memory  management 
directives  has  been  included  in  the  system  on  which  the  task  is  to 
run. 
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Several  large  classes  of  tasks  can  be  handled  effectively  when   built 

as   overlay   structures.    For  example,  a  task  that  moves  sequentially 

through  a  set   of   modules   is   well   suited   to   ure   as  an   over^.ay 

structure.    A   task  that  selects  one  of  a  set  of  modules  according  to 

the  value  of  an  item  of  input  data  io  aliio  well  suited  to  use  as  an 
Cv/erlay  structure. 

Tasks  that  have  separate  I-  and  D-space  may  also  use  overlays  where 
the  root  has  instructions  and  data  separately  defined  by  PSECTs ,  and 
each  individual  segment  of  the  task  also  has  instructions  and  data 
separately  defined.  Chapter  7  contains  more  information  about  I-  and 
D-space  tasks. 


3.1.1   Disk-Resident  Overlay  Structures 

Disk-resident  overlays  conserve  virtual  address  space  and  physical 
memory  by  sharing  them  with  other  overlays.  Segments  that  are 
logically  independent  need  not  be  present  in  memory  at  the  same  time. 
They,  therefore,  can  occupy  a  common  physical  area  in  memory  (and, 
therefore,  common  virtual  address  space)  whenever  either  needs  to  be 
used  . 

The  use  of  disk-resident  overlays  is  shown  in  this  section  by  an 
example,  task  TKl,  which  consists  of  four  input  files.  Each  input 
file  consists  of  a  single  module  with  the  same  name  as  the  file.  The 
task  is  bui^t  by  the  command 

>TKB  TK1=0VRLAY.0DL/MP 

and  the  file  OVRLAY.OUL  contains  the  modules  CNTRL,  A,  D,  C  in  an 
overlay  description  for  the  task  being  built.  The  /MP  switch 
speci^^ies  that  the  input  file  is  an  Overlay  Description  Language  (ODL) 
file. 

In  this  example,  the  modules  A,  B,  and  C  are  logically  independent; 
that  is: 

A  does  not  call  B  or  C  and  does  not  use  the  data  of  B  or  C. 

B  does  not  call  A  or  C  and  does  not  use  the  data  of  A  or  C. 

C  does  not  call  A  or  B  and  does  not  use  the  data  of  A  or  B. 

A  disk-resident  overlay  structure  can  be  defined  in  which  A,  B,  and  C 
are  overlay  segments  that  occupy  the  same  storage  area  in  physical 
memory.   The  flow  of  control  for  the  task  is  as  follows: 

CNTRL  calls  A  and  A  returns  to  CNTRL. 

CNTRL  calls  B  and  B  returns  to  CNTRL. 

CNTRL  calls  C  and  C  returns  to  CNTRL. 

CNTRL  calls  A  and  A  returns  to  CNTRL. 

In  this  example,  the  loading  of  overlays  occurs  only  four  times  during 

the   execution   of  the  task.   Therefore,  the  virtual  address  space  and 

physical  memory  requirements  of  the  task  can  be  reduced  without  unduly 
increasing  the  overhead  activity. 


The  effect  of  the  use  or  an  o/erlay  structure  on  allocating  virtual 
address  space  and  pliysica.l  memory  for  task  TKl  is  described  in  the 
following  paragraphs. 


• 
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The  lengths  of  the  modules  are: 

Nodule  Length  (in  Oc^al) 

CNTRL  20000  bytes 

A  30000  bytes 

B  20000  bytes 

C  14000  bytes 

Figure  3-1  shows  the  virtual  address  space  and  physical  memory 
required  as  a  result  of  building  TKl  as  a  single-segment  task  on  a 
system  with  memory  management  hardware. 

The  virtual  address  space  and  physical  memory  requirement  to  build  TKl 
as  a  single-segment  task  is  104000 (octal)  bytes. 

In  contrast,  Figure  3-2  shows  the  virtual  address  space  and  physical 
memory  required  as  a  result  of  building  TKl  as  a  multisegment  task  and 
using  the  overlay  capability. 

The  multisegment  task  requires  50000 (octal)  byt  'S. 

NOTE 

In  addition  to  the  storage  required  for 
modules  A,  B,  and  C,  storage  is  required 
for  overhead  in  handling  the  overlay 
structures.  This  overhead  is  not 
reflected  in  this  example. 

In  using  the  overlay  capability,  the  total  amount  of  virtual  address 
space  and  physical  memory  required  for  the  task  is  determined  by  the 
sum  of  the  length  of  the  root  segment  and  the  length  of  the  longest 
overlay  segment.  Overlay  segments  A  and  B  in  this  example  are  much 
longer  than  overlay  segment  C.  If  A  and  B  are  divided  into  sets  of 
logically  independent  modules,  task  storage  requirements  can  be 
further  reduced.  Segment  A  can  be  divided  into  a  control  program  (AO) 
and  two  overlays  (Al  and  A2) .  Segment  A2  can  then  be  divided  into  the 
main  part  (A2)  and  two  overlays  (A21  and  A22).  Similarly,  segment  B 
can  be  divided  into  a  control  module  (BO)  and  two  overlays  (Bl  and 
B2)  . 

Figure  3-3  shows  the  virtual  address  space  and  physical  memory 
required  for  the  task  produced  by  the  additional  overlays  defined  for 
A  and  B. 

As  a  single-segment  task,  TKl  requires  104000 (octal)  bytes  of  virtual 
address  space  and  physical  memory.  The  first  overlay  structure 
reduces  the  requirement  by  34000(octal)  bytes.  The  second  overlay 
structure  further  reduces  the  requirement  by  14000 (occal)  bytes. 

The  vertical  and  horizontal  lines  in  the  diagrams  of  Figures  3-2  and 
3-3  represent  the  state  of  virtual  address  space  and  physical  memory 
at  variojs  times  during  the  calling  sequence  of  TKl.  For  example,  in 
Figure  3-3  the  leftmost  vertical  line  in  both  diagrams  shows  virtual 
address  space  and  physical  memory,  respectively,  when  CNTRL,  AO ,  and 
Al  are  loaded.  The  next  vertical  line  shows  virtual  address  space  and 
physical  memory  when  CNTRL,  AO ,  A2 ,  and  A21  are  loaded,  and  so  on. 
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lines  in  the  diagrams  of  Figures  3-2  and   3-3   indicate 

space  and  physical  memory.   For 


The  horizontal 

segments   that   share   virtual  address 
example,  in  Figure  3-3,  the  uppermost 
region   in   both   diagrams   shows   Al, 
which  can  use  the  same  virtu.il  address 
next  horizontal  line  shows  Al ,  A2 ,  Bl, 


horizontal  line  of  the  task 
A21,  A22,  Bl,  82,  and  C,  all  ot 
space  and  physical  memory.  The 
B2>  and  C,  and  so  on. 
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Figure  i-l      TKl  Built  As  a  Single-Segment  Task 
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Figure  3-2   TKl  Built  As  a  Mult i segment  Task 


3.1.2   Memory-Resident  Overlay  Structures  (Not  Supported  on  RSX-llS) 

TKB  provides  foe  creating  overlay  segments  that  are  loaded  from  disk 
only  the  first  time  they  are  referenced.  Tliereafter,  they  reside  in 
memory.  Memory-resident  overlays  share  virtual  address  space  just  as 
disk-resident  overlays  do  taut,  unlike  disk-resident  overlays, 
memory-resident  overlays  do  not  share  physical  memory.  Instead,  they 
reside  in  separate  areas  of  physical  memory,  each  segment  aligned  on  a 
32-word  boundary.   Memory-resident  overlays  save  time   for   a   running 
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task  because  they  do  not  need  to  be  copied  from  a  secondary  storage 
device  each  time  they  are  to  overlay  other  segments.  "Loading"  a 
memory-resident  overlay  reduces  to  mapping  a  set  of  shared  virtual 
addresses  to  the  unique  physical  area  of  memory  containing  the 
overlaying  segment. 

The  use  of  memory-resident  overlays  is  shown  in  this  section  by  an 
example,  task  TK2,  which  consists  of  four  input  files.  Each  input 
file  consists  of  a  single  module  with  the  same  name  as  the  file.  The 
task  is  built  by  the  command 

>TKB  TK2=OVRLAY2.0DL/MP 

and  the  file  OVRLAYZ.ODL  contains  the  modules  CNTRL,  D,  E,  and  F  in  an 
overlay  description  for  the  task  being  built.  The  /MP  switch 
specifies  that  the  input  file  is  an  Overlay  Description  Language  (ODL) 
file. 

In  this  example,  the  modules  D,  E,  and  F  are  logically  independent; 
that  is: 

D  does  not  call  E  or  F  and  does  not  use  the  data  of  E  or  F. 

E  does  not  call  D  or  F  and  does  not  use  the  data  of  D  or  F. 

F  does  not  call  D  or  E  and  does  not  use  the  data  of  D  or  E. 

A  memory-resident  overlay  structure  can  be  defined  in  which  D,  E,   and 

F   are  overlay  segments  that  occupy  separate  physical  memory  locations 

but  the  same  virtual  address  space.  The  flow  of  control  lor  the  task 
is  as  follows: 

CNTRL  calls  D  and  D  returns  to  CNTRL. 

CNTRL  calls  E  and  E  returns  to  CNTRL. 

CNTRL  calls  F  and  F  returns  to  CNTRL. 

The  effect  of  the  use  of  a  memory-resident  overlay  structure  on 
allocating  virtual  address  space  and  physical  memory  for  task  TK2  is 
described  in  the  following  paragraphs. 

The  lengths  of  the  modules  are: 

Module     Length  (in  Octal) 

CNTRL  20000 

D  10000 

E  14000 

F  12000 

Figure  3-4  shows  the  virtual  address  space  and  physical  memory 
requirements  as  a  result  of  building  TK2  as  a  single-segment  task  on  a 
system  with  memory  management  hardware. 

The  virtual  address  space  and  physical  memory  requirements  when  TK2  is 
built  as  a  single-segment  task  is  56000(octal)  bytes. 

If  TK2  is  built  using  the  Task  Builder's  memory-resident  overlay 
capability,  the  relationship  of  virtual  addtess  space  to  physical 
memory  changes,  as  shown  in  Figure  3-5. 
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Figure    3-3       TKl    Built    with    Additional    Overlay    Defined 
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Figure  3-4   TK2  Built  As  a  Single-Segment  Task 
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Figure  3-5   TK2  Built  As  a  Memory- Resident  Overlay 


The  physical  memory  raquirements  for  TK2  do  not  change  (56000 (octal) 
bytes)  ,  but  the  virtual  address  space  requirements  have  been  reduced 
to  34000(octal)  bytes.  This  represents  a  savings  in  virtual  address 
space  of  22000 (octal)  bytes. 
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NOTE 


In  addition  to  the  storage  required  for 
modules  D,  E,  and  F,  storage  is  required 
for  overhead  in  handling  the  overlay 
structures.  This  overhead  is  not 
reflected  in  this  example. 


In  Figure  3-5,  the  vertical  and  horizontal  lines  in  the  virtual 
address  space  diagram  represent  the  state  of  virtual  address  space  at 
various  times  during  the  calling  sequence  of  TK2.  The  leftmost 
vertical  line  shows  virtual  address  space  when  CNTRL  and  D  are  loaded 
and  mapped.  The  next  vertical  line  shows  virtual  address  space  when 
CNTRL  and  E  are  loaded  and  mapped.  The  third  vertical  line  shows 
virtual  address  space  when  CNTRL  and  F  are  loaded  and  mapped. 


The  uppermost  horizontal  line  of  the  task  region  shows 
D,  Er  and  F  share  virtual  address  space. 


that   segments 


When  TK2  is  activated,  the  Executive  loads  TK2'8  root  segment  into 
physical  memory.  The  Executive  loads  segments  D,  E,  and  F  into  memory 
as  they  are  called.  Once  all  segments  in  the  structure  have  been 
called,  "loading"  of  the  overlay  segments  reduces  to  the  remapping  of 
virtual  address  space  to  the  physical  locations  in  memory  where  the 
overlay  segments  permanently  reside.  Figures  3-6  and  3-7  illustrate 
the  relationship  between  virtual  address  space  and  physical  memory  for 
task  TK2  during  four  time  periods: 


•   TIME  1  (Figure  3-6A)  -  TK2  is  run  and   the   system   loads 
root  segment  (CNTRL)  into  physical  mr»mory  and  maps  to  it. 


the 


•  TIME  2  (Figure  3-6B)  -  CNTRL  calls  segment  D.  The  system 
loads  segment  D  into  physical  memory  and  maps  to  it.  Segment 
D  returns  to  CNTRL. 

•  TIME  3  (Figure  3-7A)  -  CNTRL  calls  segment  E.  The  system 
loads  segment  E  into  physical  memory,  unmaps  from  segment  D, 
and  maps  to  segment  E.   Segment  E  returns  to  CNTRL. 

•  TIME  4  (Figure  3-7B)  -  CNTRL  calls  segment  F.  The  system 
loads  segment  F  into  physical  memory,  unmaps  from  segment  E, 
and  remaps  to  segment  F.   Segment  F  returns  to  CNTRL. 
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Figure  3-6A  Time  1 
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Figure  3-7A   Relationship  Between  Virtual  Address  Space 
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Figure  3  7B  Time  4 
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Figure  3-7B 


Relationship  Between  virtual  Address  Space 
and  Physical  Memory  --  Time  4 


It  is  important  to  be  careful  in  choosing  whether  to  have 
memory-resident  overlays  in  a  structure.  Carelessly  using  these 
segments  can  result  in  inefficient  allocation  of  virtual  address 
space,  because  TKB  allocates  virtual  address  space  in  bloclcs  of  4K 
words.  Consequently,  the  length  of  each  overlay  segment  should 
approach  that  limit  if  you  are  to  minimize  waste.  (A  segment  that  is 
one  word  longer  than  4K  words,  for  example,  is  allocated  8K  words  of 
virtual  address  space.  All  but  one  word  of  the  second  4K  words  is 
unusable . ) 
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You  can  also  conserve  physical  memory  by  ma  int<i  ini  itj  control  over  the 
contents  of  each  s^qment .  Including  a  module  in  several 
memory-resident  segments  that  overlay  one  another  causes  physical 
memory  to  be  reserved  for  each  extra  copy  of  that  module.  Common 
modules,  Including  those  fron  the  system  object  module  library 
(SYSLIB)  ,  should  be  placed  in  a  segment  that  can  be  accessed  from  all 
referencing  seoments. 

The  primary  criterion  for  choosing  to  have  memory-resident  overlays  ia 
the  need  to  save  virtual  address  space  when  disk-resident  overlays  are 
either  undesirable  (because  they  would  slow  down  the  system 
unacceptabl y)  ,  or  impossible  (because  the  segments  are  part  of  a 
resident  library  or  other  shared  region  that  must  permanently  reside 
in  memory) . 

Memory-resident  overlays  can  help  you  use  l.irge  systems  to  better 
advantage  because  of  the  time  savings  realized  when  a  large  amount  of 
physical  memory  is  available.  Resident  libraries,  in  particular,  can 
benefit  from  the  virtual  address  space  saved  when  they  are  divided 
into  memory-resident  segments. 


3.2   OVERLAY  TREE 

The  arrangement  of  overlay  segments  within  the  virtual  address  space 
of  a  task  can  be  represented  schematically  as  a  tree-like  structure. 
Each  branch  of  the  tree  represents  a  segment.  Parallel  branches 
denote  segments  that  overlay  one  another  and  therefore  have  the  same 
virtual  address;  these  segments  must  be  logically  independent. 
Branches  connected  end  to  end  represent  segments  that  do  not  share 
virtual  address  space  with  each  other;  these  segments  need  not  be 
logically  independent. 

TKB  provides  an  Overlay  Description  Language  (ODL)  for  representing  an 
overlay  structure  consisting  of  one  or  more  trees  ( che  ODL  is 
described  in  Section  3.4)  . 

The  single  overlay  tree  shown  in  Figure  3-8  represents  the  allocation 
of  virtual  address  space  for  TKl  (see  Section  3.1.1). 

The  tree  has  a  root  (CNTRL)  and  threa  main  branches  (AO,  BO,  and  C) . 
It  also  has  six  leaves  (Al,  A21,  A22,  Bl,  B2,  an-i  C)  . 

The  tree  has  as  many  paths  as  it  has  leaves.  The  path  down  is  defined 
from  the  leaf  to  the  root.   For  example: 

A21-A2-A0-CNTRL 

The  path  up  is  defined  from  the  root  to  the  leaf.   Pot  example: 

CNTRL-BO-Bl 

Knowing  the  properties  of  the  tree  and  its  paths  is  important  to 
understanding  the  overlay  loading  mechanism  and  the  resolution  of 
global  symbols. 
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Figure  3-8   Overlay  Tree  for  TKl 


3.2.1   Loading  Mechanism 

Modules  can  call  other  modules  that  exist  on  the  same  path.  The 
module  CNTRL  (Figure  3-8)  is  common  to  every  path  of  the  tree  and, 
therefore,  can  call  and  be  called  by  every  module  in  the  tree.  The 
module  A2  can  call  the  modules  A21,  A22,  AO ,  and  CNTRL;  but  A2  cannot 
call  Al ,  Bl,  B2,  BO,  or  C. 

When  a  module  in  one  overlay  segment  calls  a  module  in  another  overlay 
segment,  the  called  segment  must  be  in  memory  and  mapped,  or  must  be 
brought  into  memory.  The  methods  for  loading  overlays  are  described 
in  Chapter  4. 


3.2.2   Resolution  of  Global  Symbols  in  a  Multisegment  Task 

In  resolving  global  symbols  for  a  multisegment  task,  TKB  performs  the 
same  activities  that  it  does  for  a  single-segment  task.  The  rules 
defined  in  Chapter  2  for  resolving  global  symbols  in  a  single-segment 
task  apply  also  in  this  case,  but  the  scope  of  the  global  symbols  is 
altered  by  the  overlay  structure. 

In  a  single-segment  task,  any  module  can  refer  to  any  global 
definition.  In  a  multisegment  task,  however ,  a  module  can  only  refer 
to  a  global  symbol  that  is  defined  on  a  path  that  passes  through  the 
called  segment. 

The  following  points,  illustrated  in  the  tree  diagram  in  Figure  3-9, 
describe  the  two  distinct  cases  of  multiply  defined  symbols  and 
ambiguously  defined  symbols. 

In  a  single-segment  task,  if  you  define  two  global  symbols  with  the 
same  name,  the  symbols  are  multiply  defined  and  an  error  message  is 
produced . 

In  a  multisegment  task,  you  can  define  two  global  symbols  with  the 
same  name  if  they  are  on  separate  paths,  and  not  referenced  from  a 
segment  that  is  common  to  both. 

If  you  define  a  global  symbol  more  than  once  on  separate  paths,  but 
they  are  referenced  from  a  segment  that  is  common  to  both,  the  symbol 
ir>  ambiguously  defined.  If  you  define  a  global  symbol  more  than  once 
on  a  single  path,  it  is  multiply  defined. 
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TKB's  procecluEe  for  cesolvin>j  global  symbols  is  summarized  as  follows: 

1.  TKB  selects  an  overl.iy  segment  for  processing. 

2.  TKB  scans  each  mocJule  in  the  segment  for  global  ciefinitiona 
an<3  references. 

3.  If  the  symbol  is  a  definition,  TKB  searches  all  segments  on 
paths  that  pass  through  t)ie  segment  being  processed,  and 
looks  for  references  that  must  be  resolved. 

4.  If  the  symbol  is  a  reference,  TKB  performs  the  tree  search  as 
described  in  step  3,  looking  for  an  existing  definition. 

5.  If  the  symbol  is  new,  TKB  enters  it  in  a  list  of  global 
symbols  associated  with  the  segment. 

Overlay  segments  are  selected  for  processing  in  an  order  corresponding 
to  their  distance  from  the  root.  That  is,  TKB  processes  the  segment 
farthest  from  the  root  first,  before  processing  an  adjoining  segment. 

When  TKB  processes  a  segment,  its  search  for  global  symbols  proceeds 
as  follows: 

1.  The  segment  being  processed 

2.  All  segments  toward  the  root 

3.  All  segments  away  from  the  root 

4.  Ail  co-trees  (see  Section  3.5) 

Figure  3-9  illustrates  the  resolution  of  global  symbols  in  a 
multisegment  task. 
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Figure  3-9   Resolution  of  Global  Symbols  in  a  Multisegment  Task 
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The  following  notes  discuss  the  resolution   of   references   in   Figure 
3-9: 

1.  Tho  qlobal  symbol  0  is  defined  in  both  segment  AO  and  segment 
BO.  The  references  to  Q  in  segment  A22  and  in  segment  Al  are 
resolved  by  the  definition  in  AO .  The  reference  to  Q  in  Bl 
is  resolved  by  the  definition  in  BO.  The  two  definitions  of 
0  are  distinct  in  all  respects  and  occupy  different  overlay 
paths . 

2.  The  global  symbol  R  is  defined  in  segment  A2 .  The  reference 
to  R  in  A22  is  resolved  by  the  definition  in  A2  because  there 
is  a  path  to  the  reference  from  the  definition 
(CNTRL-A0-A2-A22) .  The  reference  to  R  in  Al,  however,  is 
undefined  because  there  is  no  definition  for  R  on  a  path 
through  Al. 

3.  The  global  symbol  S  is  defined  in  both  segment  AO  and  segment 
BO.  References  to  S  from  segments  Al,  A21,  or  A22  are 
resolved  by  the  definition  in  AO ,  and  references  to  S  in  Bl 
and  B2  are  resolved  by  the  definition  in  BO.  However,  the 
reference  to  S  in  CNTRL  cannot  be  resolved  bocause  tnere  are 
two  definitions  of  S  on  separate  paths  through  CNTRL.  The 
global  symbol  S  is  ambiguously  defined. 

4.  The  global  symbol  T  is  defined  in  both  segment  A21  and 
segment  AO .  Since  there  is  a  single  path  through  the  two 
definitions  (CNTRL-A0-A2-A21) ,  the  global  symbol  T  is 
multiply  defined. 


3.2.3   Resolution  of  Global  Symbols  from  the  Default  Library 

The  process  of  resolving  global  symbols  may  require  two  passes  over 
the  tree  structure.  The  global  symbols  discussed  in  the  previous 
section  are  included  in  user-specified  input  modules  that  TKB  scans  in 
the  first  pass.  If  any  undefined  symbols  remain,  TKB  initiates  a 
second  pass  over  the  structure  in  an  attempt  to  resolve  such  symbols 
by  searching  the  default  object  module  library  (normally 
LBO : [ 1 ,1] SYSLIB.OLB) .  TKB  reports  any  undefined  symbols  remaining 
after  its  second  pass. 

When  multiple  tree  structures  (co-trees)  are  defined,  as  described  in 
Section  3.5,  any  resolution  of  global  symbols  across  tree  structures 
during  a  second  pass  can  result  in  multiple  or  ambiguous  definitions. 
In  addition,  such  references  can  cause  overlay  segments  to  be 
inadvertently  displaced  from  memory  by  the  overlay  loading  routines, 
thereby  causing  run-time  failures.  To  eliminate  these  conditions,  the 
tree  search  on  the  second  pass  is  restricted  to: 

•  The  segment  in  which  the  undefined  reference  has  occurred 

•  All  segments  in  the  current  tree  that  are  on   a   path   through 
the  segment 

•  The  root  segment 

When  the  current  segment  is  the  main  root,  the  tree  search  is  extended 
to  all  segments.  You  can  unconditionally  extend  the  tree  search  to 
all  segments  by  including  the  /PU  (full)  switch  in  the  task  image  file 
specification.  (Refer  to  Chapter  10  for  a  description  of  the  /FU 
switch .) 
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3.2.4   Allocation  of  Proqram  Section*  in  a  Mult i segment  Task 


One  of  a  program  section's 
section   is   local   (LCL) 
global  (GBL) . 


attributes  infiiccites   whether   the   program 
to  the  segment  in  which  it  is  defined  or  is 


Local  program  sections  with  the  same  name  can  appear  in  any  number  of 
segments.  TKB  allocates  virtual  address  space  for  each  local  program 
section  in  the  segment  in  which  it  is  declared.  Global  program 
sections  that  have  the  same  name,  however,  must  be  resolved  by  TKB. 

When  a  global  program  section  is  defined  in  several  overlay  segments 
along  a  common  path,  TKB  allocates  all  virtual  address  space  for  the 
program  section  in  the  overlay  segment  closest  to  the  root. 

FORTRAN  common  blocks  are  translated  into  global  program  sections  with 
the  overlay  (OVR)  attribute.  In  Figure  3-10,  the  common  block  COMA  is 
defined  in  modules  A2  and  A21.  TKB  allocates  the  virtual  address 
space  for  COMA  in  A2  because  that  segment  is  closer  to  the  root  than 
the  segment  that  contains  A21. 

If  the  segments  AO  and  BO  use  the  common  block  COMAB,  however,  TKB 
allocates  the  virtual  address  space  for  COMAB  in  both  the  segment  that 
contains  AO  and  the  segment  that  contains  BO.  AO  and  BO  cannot 
communicate  through  COMAB.  When  the  overlay  segment  containing  BO  is 
loaded,  any  data  stored  in  COMAB  by  AO  is  lost. 

You  can  specify  the  allocation  of  program  sections  explicitly.  If  AO 
and  BO  need  to  share  the  contents  of  COMAB,  you  can  force  the 
allocation  of  this  program  section  into  the  root  segment  by  the  use  of 
tha  .PSECT  directive  of  the  Task  Builder's  overlay  description 
language,  described  in  Section  3.4. 
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Figure  3-10   Resolution  of  Program  Sections  for  TKl 

3.3   OVERLAY  DATA  STRUCTURES  AND  RUN-TIME  ROUTINES 

When  TKB  constructs  an  overlaid  task,  it  builds  additional  data 
structures  and  adds  them  to  the  task  image.  The  data  structures 
contain  information   about   the   overlay   segments   and   describe   the 
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calationship  of  aach  ••gincnt  In  the  tc«e  to  the  other  segmenta  in  the 
tree.  TKB  also  includes  into  the  task  image  a  number  of  system 
library  routines  (called  overlay  run-time  routines).  The  overlay 
run-time  routines  use  the  data  structures  to  facilitate  the  loading  of 
the  segments  and  to  provide  the  necessary  linkages  from  one  segment  to 
another  at  run  time. 

TKB  links  the  majority  of  data  structures  and  all  of  the  overlay 
run-time  routines  into  the  root  segment  of  the  task.  The  number  and 
type  of  data  structures,  and  the  functions  the  routines  perform, 
depend  on  two  considerations: 

•  Whether  the  task  is  built  to  use  the  Task   Builder's   autoload 
or  manual  load  facilities 

•  Whether   the   overlay  segment   is  memory   resident   or  disk 
resident 

These  considerations  have  a  marked  impact  on  the  size  and  operation  of 
the  task.  Chapter  4  describes  the  Task  Builder's  autoload  and  manual 
load  facilities  and  describes  the  methods  for  loading  overlays. 
Appendix  B  describes  the  data  structures  and  their  contents  in  detail. 

The  contents  of  the  root  segment  for  a  task  with  an  overlay  structure 
are  discussed  briefly  in  the  following  sections. 


3.3.1   Overlaid  Conventional  Task  Structures 

Depending  on  the  considerations  just  discussed,  some  or  all  of  the 
following   data   structures   are   required   by   the   overlay   run-time 

rout  i  nes : 

•  Segment  tables 

•  Autoload  vectors 

•  Window  descriptors 

•  Region  descriptors 

Figure  3-11  shows  a  typical  overlay  root  segment  structure. 

There  is  a  segment  descriptor  for  every  segment  in  the  task.  The 
descriptor  contains  information  about  the  load  address,  the  length  of 
the  segment,  and  the  tree  linkage. 

In  an  autoloadable ,  overlaid  task,  autoload  vectors  appear  in  the  root 
segment  and  in  every  segment  that  calls  modules  in  another  segment 
located  farther  away  from  the  root  of  the  tree.  All  references  to 
resident  libraries  are  resolved  through  autoload  vectors  in  the  root. 

Window  descriptors  are  allocated  whenever  a  memory-resident  overlay 
structure  is  defined  for  the  task.  The  descriptor  contains 
information  required  by  the  Create  Address  Window  system  directive 
(CRAW$) .  One  descriptor  is  allocated  for  each  memory-resident  overlay 
segment . 

Region  descriptors  are  allocated  whenever  a  task  is  linked  to  a  shared 
region  containing  memory-resident  overlays.  The  descriptor  contains 
information  required  by  the  Attach  Region  system  directive  (ATRG$) . 
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Figure  3-11   Typical  Overlay  Root  Segment  Structure 


3.3.2  Overlaid  I-  and  D-Space  Task  Structures 

Overlaid  I-  and  D-space  tasks  contain  data  structures  similar  to  those 
in  a  conventional  task.  These  data  structures  differ  cnly  in  their 
virtual  address  space  allocation  (mapping) ,  and  some  structures  are 
mapped  in  two  different  address  spaces. 

Figure  3-12  shows  a  typical  overlaid  I-  and  D-space  task  with  an 
up- tree  segment. 

The  structures  located  in  data  space  are: 

•  Segment  descriptors 

•  Window  descriptors 

•  Region  descriptors 

•  Autoload  vectors  (the  data  part) 

Autoload  vectors  contain  data  and  instructions.  Therefore,  TKB 
locates  the  instruction  part  of  the  autoload  vector  in  I-space  and  the 
data  part  in  D-space.  Each  segment  of  an  autoloadable  overlaid  I-  and 
D-space  task  may  have  an  instruction  part  and  a  data  part.  Therefore, 
each  I-  and  D-space  segment  in  such  a  task  would  have  its  vecto's 
separated  into  an  instruction  par';  and  a  data  part. 
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Th«  itructuces  located  In  instruction  space  are: 
•   Autoload  vectors  'Instruction  part) 
e   Segment  return  point 
e   Overlay  runtime  system  code  (root  segment  only) 
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Figure  3-12   Typical  Overlaid  I-  and  D-Space  Task  with  Up-Tree  Segment 
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3.4   OVERLAY  DESCRIPTION  LANGUAGE 

TKB  provides  a  language,  called  the  Overlay  Description  Language 
(DDL),  that  allows  you  to  describe  the  overlay  structure  of  a  task. 
An  overlay  description  is  a  text  file  consisting  of  a  series  of  ODL 
directives,  one  directive  per  line.  Each  line  may  have  as  many  as  132 
charac*:er3.  You  enter  the  name  of  this  file  in  a  TKB  command  line, 
and  identify  it  as  an  ODL  file  by  specifying  the  /MP  switch  (see 
Chapter  10)  to  the  file  name.  For  example,  the  following  TKB  command 
line  specifies  an  ODL  file: 

>TKB  TASK1=0VRLAY/MP 

If  you  specify  an  ODL  file  to  TKB,  it  must  be  the  only  input  file  you 
speci  ty . 

A  command  line  in  an  ODL  file  takes  the  form 

label:   directive   argument-list   ;comment 

A  label  is  required  only  for  the  .FCTR  directive  (see  Section  3.4.2). 
Labels  cannot  be  used  with  th^  other  directives. 

The  ODL  directives  are  iisted  below  and  described  in  Sections  3.4.1 
through  3.4.6: 

•  .ROOT  and  .END 

•  .FCTR 

•  .NAME 

•  .PSECT 

•  ?  (at  sign;   indirect  command  file  specifier) 

The  ODL  directives  can  act  upon  the  following  items:  named  input 
files,  overlay  segments,  program  sect  ons,  and  lines  in  the  ODL  file 
itself.  These  items  follow  each  direct  ve  on  the  same  line  as  the 
directive,  and  form  an  argument-list.  Operators,  such  as  the  hyphen, 
exclamation  point,  and  comma,  group  the  argument-list  items  (named 
task  elements)  or  attach  attributes  to  them. 

If  the  named  task  »?lement  is  a  file,  you  can  enter  a  rorrplete  file 
specification.  Defaults  for  omitted  parts  of  the  file  specification 
are  as  described  in  Chapters  1  and  10,  except  that  the  default  device 
is  SYO:,  and  the  default  UFD  is  taken  "rem  the  terminal  UIC. 

In  addition,  the  following  restrictions  apply  to  argument-lists: 

•  You  can  only  use  the  dot  character  (.)  in  a  tile  name. 

•  Comments  cannot  appear  on  a  line  ending  with  a  file  name. 
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.ROOT  and  .END  Directives 


The  .ROOT  directive  defines  the  structure  of  the  overlaid  task. 
Because  of  this,  .ROOT  usually  appears  first  in  the  overlay 
description.  The  .NAME  directive  may  precede  the  .ROOT  directive  in 
certain  circumstances  discussed  in  Section  3.4.4.  Each  overlay 
description  must  end  w- i;h  one  .END  directive.  The  .ROOT  directive 
tells  TKB  where  to  ::tart  building  the  tree,  and  the  ,  END  directive 
tells  TKB  where  the  input  ends. 
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The  aryuments  of  the  .ROOT  directive  use  three  operators  to  express 
concatenation,  memory  residency,  and  overlaying.  These  operators  can 
be  used  also  in  the  .FCTR  directive. 

•  The  hyphen  (-)  operator  Indicates  the  concatenation  of  virtual 
address  space.  For  example,  X-Y  means  that  sufficient  virtual 
address  space  will  bt  allocated  to  contain  module  X  and  module 
Y  simultaneously.  TKB  allocates  segment  X  and  segment  Y  in 
sequence  to  produce  one  segment. 

•  The  exclamation  poi/.*:  (!)  operator  indicates  memory  residency 
of  overlays.   (This  operator  is  discussed  in  Section  3.4.3.) 

•  The  comma  (,)  operator,  appearing  within  parentheses, 
indicates  the  overlaying  of  virtual  address  space.  For 
example,  (Y,Z)  means  that  virtua'  address  space  can  contain 
either  segment  Y  or  segment  Z.  If  no  exclamation  point  (I) 
precedes  the  left  parenthesis,  segment  Y  and  segment  Z  also 
share  physical  memory. 

The  comma  (,)  operator  is  also  used  to  define  multiple   tree 
structures  (as  described  in  Section  3.5.1). 

You  use  parentheses  to  delimit  a  group  of  segments  that  start   at   th 
same   virtual   address.    The   number   of   nested  parenthetical  groups 
cannot  exceed  16. 

For  example: 

.ROOT  X-(Y,Z-  (Z1,Z2) ) 
.END 

These  directives  describe  the  tree  and  its  corresponding  virtual 
address  space  shown  in  Figure  3-13: 


Z1 


Z2 
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Z1 

Z2 
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Figure  3-13   Tree  and  Virtual  Address  Space  Diagram 

To  create  the  overlay  description  for  the  task  TKl  in  Figure  3-3 
(Section  3.1.1),  you  could  create  a  file  called  TFIL.ODL  that  contains 
the  directives: 

.ROOT  CNTRL-(A0-(A1,A2-(A21,A22) ) ,B0-(B1,B2) ,C) 
.END 

To  build  the  task  with  that  overlay  structure,  you  would  type: 

>TKB  TK1=TFIL/MP 

The  /MP  switch  in  the  command  string  above  tells  TKB  that  there  is 
only  one  input  file  iTFIL.ODL),  and  that  this  Ei lo  contains  the 
overlay  description  for  the  task. 
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3.4.2   .rCTR  Directive 

The  .FCTK  directive  allows  you  to  build  large,  complex  trees  and 
represent  them  cl.early. 

The  .FCTR  directive  has  a  label  at  the  beginning  of  the  ODL  line  that 
is  pointed  to  by  a  reference  in  a  .ROOT  or  another  .FCTR  statement. 
The  label  must  be  unique  with  respect  to  module  names  and  other 
labels.  The  .FCTR  directive  allows  you  to  extend  ^he  tree  description 
beyond  a  single  line,  enabling  you  to  provide  a  clearer  description  of 
the  overlay.   (There  can  be  only  one  .ROOT  directive.) 

For  example,  to  simplify  the  tree  given  in  the  file  TFIL  (described  in 
Section  3.4.1),  you  could  use  the  .FCTR  directive  in  the  overlay 
description  as  follows: 

.ROOT  CNTRL-(AFCTR,BFCTR,C) 

AFCTR:     .FCTR  A0-(A1,A2-(A21,A22) ) 

BFCTR:      .FCTR  B0-(B1,B2) 

.END 

The  label  BFCTR  is  used  in  the  .ROOT  directive  to  designate  the 
argument  B0-(B1,B2)  of  the  .FCTR  directive.  The  resulting  overlay 
description  is  easier  to  interpret  than  the  original  description.  The 
tree  consists  of  a  root,  CNTRL,  and  three  main  branches.  Two  of  the 
main  branches  have  sub-branches. 

The  .FCTR  directive  can  be  nested  to  a  level  of  16.  For  example,  you 
could  further  modify  TFIL  as  follows: 

.ROOT  CNTRL- (AFCTR, BFCTR, C) 
AFCTR:     .FCTR  AO- ( Al , A2FCTR) 
A2FCTR:    .FCTR  A2-(A21,A22) 
BFCTR:     .FCTR  B0-(B1,B2) 

.END 


3.4.3   Arguments  for  the  .FCTR  and  .ROOT  Directives 

The  arguments  for  the  .FCTR  and  .ROOT  directives  may  have  different 
forms  or  syntax.  The  examples  in  this  chapter  use  forms  such  as  Al , 
Bl,  X,  and  y  for  clarity,  but  the  actual  arguments  that  you  use  may 
have  somewhat  different  names.  This  section  lists  the  forms  that  the 
arguments  may  ta)<e  for  these  directives.  If  you  use  an  argument  that 
does  not  fall  into  one  of  the  following  five  categor.es,  TKB  takes  the 
argument  as  that  of  the  name  of  an  object  module  file;  in  other 
words,  the  file  name  that  you  use  must  have  an  extension  of  .OBJ. 


3.4.3.1   Named  Input  File  -  You  may  use  a  named  input   file   that   has 
the  object  file  format.   For  example, 

CALC:    .FCTR  [7, 54) MULT. OBJ 

The  defajlt  is  .OBJ. 
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3.4.3.2  Specific  Library  Modules  -  You  may  name  and  therefore  use 
specific  object  modules  from  a  library  file.   For  example, 

BAKER:    .PCTR  ClOO  ,  3 1  COOK  I E/LB :CHI P : OAT 

where  COOKIE. OLB  Is  the  library  file  and  CHIP  and  OAT  are  the  modules 
that  you  want  to  extract  from  the  file.  The  default  extension  is  .OLB 
and  it  need  not  be  specified  as  part  of  the  argument. 


3.4.3.3   A  Library  to  Resolve  Refer -nces  Not  Previously  Resolved  -  You 

may  specify  a  library  as  an  argument  in  a  .FCTR  statement  after 
extracting  specific  modules  in  a  previous  .FCTR  statement.  TKB  uses 
the  library  to  resolve  symbols  that  may  still  be  unresolved  after 
extracting  the  modules.   For  example, 

BAKER:    .FCTR  ( 300 , 3 ) COOKI E/LB :CHI P :OAT 
LIB:      .FCTR  LB : [ 1 ,4 ) RECI PE/LB 


3.4.3.4  A  Section  Name  Used  in  a  .PSECT  Directive  -  You  may  use  the 
name  that  you  used  as  a  program  section  name  in  the  .PSECT  directive 
as  the  argument  in  a  .FCTR  statement.   For  example, 

.PSECT   COM,GBL,D,RW,OVR 

FSTCOM:  .FCTR    COM 


3.4.3.5   A  Segment  Name  Used  in  a  .NAME  Directive  -  You  may  use   the 

name   that   you   specified   as   the   name   of   a   segment  in  the  .NAME 
directive.   For  example, 

.NAME    SEG1,GBL,DSK 
OVLY:   .FCTR    SEG1-M0D1-M0D2 


3.4.4   Exclamation  Point  Operator 

The  exclamation  point  operator  allows  you  to  specify  memory-resident 
overlay  segments  (see  Section  3.1.2).  You  specify  memory  residency  by 
placing  an  exclamation  point  (!)  immediately  before  the  left 
parenthesis  enclosing  the  segments  to  be  affected.  The  overlay 
description  for  task  TK2  in  Figure  3-4  (Section  3.1.2)  is  as  follows: 

.ROOT  CNTRL-! (D,E,F) 
.END 

In  the  example  above,  segments   D,   E,  F   are   declared   resident   in 

separate   areas   of   physical  memory.  The  Task  Builder  determines  the 

single  starting  virtual  address  for  D,  E,  and  F  by  rounding  the   octal 

length   of   segment   CNTRL   up   to  the  next  4K  boundary.   The  physical 

memory  allocated  to  segments  D,  E,  and  F  is  determined  by  rounding  the 

actual  length  of  each  segment  to  the  next  32-word  boundary  (256-word 
boundary  if  the  /CM  switch  is  in  effect)  ,  and  adding  this  value  to  the 
total  memory  required  by  the  task. 
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The  exclamation  point  operator  applies  to  that  segment  immediately  to 
the  right  of  the  left  parenthesis  and  those  segments  farther  from  the 
root  on  the  same  level  with  that  segment.  In  other  words,  all 
parallel  segments  must  be  of  the  same  residency  type  (disk  resident  or 
memory  resident)  . 

The  exclamation  point  operator  applies  to  legments  at  the  same  level 
from  the  root  inside  a  pair  of  parentheses;  segments  nested  in 
parenthesis  within  that  level,  but  farther  from  the  root,  are  not 
affected . 

It  is  therefore  posslb.'e  to  define  an  overlay  structure  that  combines 
the  space-saving  attributes  of  disk-resident  overlays  with  the  speed 
of  memory-resident  overlays.   For  example: 


.ROOT   -1 (Bl- 
.END 


{B2,B3) ,C) 


In  this  example,   Bl   and   C  are 
exclamation   point   operator.    B2 
however,   because   no   exclamation 
parentheses  enclosing  them. 


declared  memory  resident  by  the 

and  B3  are  declared  disk  resident, 

point   operator   precedes    the 


Note  that  while  a  memory-resident  overlay  can  call  a  disk-resident 
overlay,  the  converse  is  not  legal;  that  is,  you  cannot  use  an 
exclamation  point  for  segments  emanating  from  a  disk-resident  segment. 
For  example,  you  cannot  build  the  following  structure: 


.RC  )T 
.END 


A-(B1-1 (B2,B3) ,C) 


this  overlay  description  is  illegal 


In  this  example,  Bl  is  declared  disk  resident;   so  it 
use  the  exclamation  point  to  declare  B2  and  B3  memory 


is   illegal 
resident . 


to 
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The  .NAME  directive  allows  you  to  name  a  segment,  and  assign 
attributes  to  the  segment.  The  name  must  be  unique  with  respect  to 
file  names,  program  section  names,  .FCTR  labels,  and  other  segment 
names  used  in  the  overlay  description.  You  use  the  .NAME  directive 
prior  to  using  the  .ROOT  or  .FCTR  directive.  The  Task  Builder 
attaches  attributes  to  a  segment  when  it  encounters  the  name  in  a 
•ROOT  or  .FCTR  directive  that  defines  the  overlay  segment.  If  you 
apply  multiple  names  to  a  segment,  the  attributes  of  the  last  name 
given  are  in  effect.   This  directive  does  the  following: 

•  Names  uniquely  a  segment  that  is   loaded   through   the   manual 
load  facility  (see  Chapter  4) 

•  Permits  a  named  data-only  segment  to   be   loaded   through   the 
autoload  mechanism 

The  format  of  the  .NAME  directive  is: 

.NAME  segname[ ,attr ]  [  ,attr] 

segname 

A  1-  to  6-character  name;   this  name  can  consist  of  the   Radix-50 
characters  A-Z,  0-9,  and  $    (the  period  (.)  cannot  be  used). 


3-27 


attr 


OVERLAY  CAPABILITY 


One  of  the  following 
GBL 


NODSK 


NOGBL 


DSK 


The  name  is  entered  in  the  segment's  global  symbol 
table. 

The  GBL  attribute  makes  it  possible  to  load 
data-only  overlay  segments  by  means  of  the  autoload 
mechanism  (see  Chapter  4). 

No  disk  space  is  allocated  to  the  named  segment. 

If  a  data  overlay  segment  has  no  initial  values,  but 
will  have  its  contents  established  by  the  running 
task,  no  space  for  the  named  segment  on  disk  need  be 
reserved.  If  the  code  attempts  to  establish  initial 
values  for  data  in  a  segment  for  which  no  disk  space 
is  allocated  (a  segment  with  the  NODSK  attribute), 
TKB  gives  a  fatal  error. 

The  name  is  not  entered  in  the  segment's  global 
symbol  table. 

If  the  GBL  attribute  is  not  present,  NOGBL  is 
assumed . 

Disk  storage  is  allocated  to  the  named  segment. 

If  the  NODSK  attribute  is  not  present,  DSK  is 
assumed . 


3.4.5.1  Example  of  The  Use  of  The  .NAME  Directive  -  In  the  following 
modified  ODL  file  for  TKl  (Figure  3-3  of  Section  3.1.1),  you  provide 
names  for  the  three  main  branches,  AO ,  BO,  and  C,  by  specifying  the 
names  in  the  .NAME  directive  and  using  them  in  the  .ROOT  directive. 
The  default  attributes  NOGBL  and  DSK  are  in  effect  for  BRNCHl  and 
BRNCH3,  but  BRNCH2  has  the  complementary  attributes  (GBL  and  NODSK) 
that  cause  TKB  to  enter  the  name  BRNCH2  into  the  segment's  global 
symbol  table  and  suppress  disk  allocation  for  that  segment.  BRNCH2 
contains  uninitialized  storage  to  be  utilized  at  run  time. 

.NAME  BRNCHl 

.NAME  BRNCH2, GBL, NODSK 

.NAME  BRNCH3 

.ROOT  CNTRL-! ( BRNCHl- AFCTR ,* BRNCH2-BFCTR , BRNCH3-C) 

AFCTR:     .FCTR  AO- ( Al , A2- ( A21 , A22 ) ) 

BFCTR:     .FCTR  B0-*!(B1,B2) 

.END 

(The  asterisk  (*)  is  the  autoload  indicator;  it  is  discussed  in 
Chapter  4.) 

You  can  load  the  data  overlay  segment  ERNCH2  by  including  the 
following  statement  in  the  prTgram: 

CALL  BRNCH2 

This  ection  is  immediately  followed  by  an  automatic  return  to  the  next 
instruction  in  the  program. 
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You  can  also  use  socjment  names  in  making  patches  with  the   ADSPAT   and 
GBLPAT  options  (see  Chapter  11). 

NOTE 

In  the  absence  of  n  unique  .NAMK 
specification,  TKH  establishes  a  segment 
name,  usinq  the  first  module  nam*  or 
library  module  name  occurring  in  the 
segment . 


3.4.6   .PSECT  Directive 

You  can  use  t-he  .PSECT  directive  to  control  the  placement  of  a  global 
program  section  in  an  overlay  structure.  The  name  of  the  program 
section  (a  1-  to  6-character  name  consisting  of  the  Radix-50 
characters  A-Z,  0-9,  and  $)  and  i^8  attributes  are  given  in  the  .PSECT 
directive.  The  attributes  used  in  the  .PSECT  dire  ti.'e  must  match 
those  in  the  actual  program  section  in  the  module.  Thus,  you  can  use 
the  name  in  a  .ROOT  or  .FCTR  statement  to  indicate  to  the  Task  Builder 
the  segment  to  which  the  program  section  will  be  allocated.  An 
example  of  the  use  of  .PSECT  is  given  in  the  modified  version  of  task 
TKl  (the  original  version  is  shown  in  Figure  3-3  in  Section  3.1.1) 
shown  below. 

In  this  example,  TKl  has  a  disk-resident  overlay  structure.  The 
example  assumes  that  the  programmer  was  careful  about  the  logical 
independence  of  the  modules  in  the  overlay  segment,  but  failed  tc  t.^ke 
into  ace  )unt  the  requirement  for  logical  independence  in  multiple 
executions  of  the  same  overlay  segment. 

The  flow  OL  task  TKl  can  be  summarized  as  follows.  CNTRL  calls  each 
of  the  overlay  segments,  and  the  overlay  segment  returns  to  CNTRL  in 
the  order  A,  B,  C,  ?.  Module  A  is  executed  twice.  The  overlay 
segment  containing  A  must  be  reloaded  for  the  second  execution. 

Module  A  uses  a  common  block  named  DATA3.  The  Task  Builder  allocates 
DATA3  to  the  overlay  segment  containing  A.  The  first  execution  of  A 
stores  some  results  in  DATA3.  The  second  execution  of  A  requires 
these  values.  In  this  disk-resident  overlay  structure,  however,  the 
values  calculated  by  the  firsu  execution  of  A  are  overlaid.  When  the 
segment  containing  A  is  read  in  for  the  second  execution,  the  common 
block  is  in  its  initial  state. 

To  permit  the  two  executions  of  A  to  communicate,  a  .PSECT  directive 
is  used  to  force  the  allocation  of  DATA3  into  tne  root.  The  indirect 
command  file  for  TKl,  TFIL.ODL,  is  modified  as  follows: 

.PSECT  DATA3,RW,GBL,REL,0VR 

.  ROOT  CNTRL-DATA3-  (  At'CTR  ,  BFCTR  ,C) 
AFCTR:     .FCTR  AO- ( Al , A2- ( A2 1 , A22 ) ) 
BFCTR:      .FCTR  B0-(B1,B2) 

.END 

The  attributes  RW,  GBL,  REL,  and  OVR  are  described  in  Chapter  2. 
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3.4.7   Indirect  Command  Files 

The  Overlay  Description  Language  processor  can  accr-pt  ODL  text 
indirectly,  that  is,  specified  in  an  indirect  command  file.  If  an  at 
sign  (@)  appears  as  the  first  character  in  an  ODL  line,  the  processor 
reads  text  from  the  file  specified  immediately  e.fter  the  at  sign.  The 
processor  accepts  the  ODL  text  from  the  file  as  input  at  the  point  in 
the  overlay  description  where  the  file  is  specified. 

For  example,  suppose  you  create  a  file,  called  BIND. ODL,  that  contains 
the  text: 


B: 


,FCTR  B1-(B2,B3) 


A  line  beginning  with  gBIND  can  replace   this   text   at   the 
where  the  text  would  have  appeared: 


posi  t ion 


Indirect 


Direct 


C: 
lasiND 


.ROOT  A-(B,C) 
.FCTR  CI- (C2,C3) 

.END 


.ROOT  A-(B,C) 

C:    .FCTR  CI- (C2,C3) 

B:    .FCTR  B1-(B2,B3) 

.END 


The  Task  Builder  allows  two  levels  of  indirection. 


3.5   MtlLTIPLE-TREE  STRUCTURES 

You  can  define  more  than  one  tree  within  an  overlay  structure.  These 
multiple  tree  structures  consist  of  a  main  tree  and  one  or  more 
co-trees.  The  root  segment  of  the  main  tree  is  loaded  by  the 
Executive  when  the  task  is  made  active,  while  segments  within  each 
co-ti'ee  are  loaded  through  calls  to  the  overlay  run-time  routines. 
Except  for  this  distinction,  all  overlay  trees  have  identical 
chTracter ist ics :  a  root  segment  that  resides  in  memory,  and  two  or 
more  overlay  segments. 

The  main  property  of  a  structure  containing  more  than  one  tree  is  that 
storage  is  not  shared  among  trees.  Any  segment  in  a  tree  can  be 
referred  to  from  another  tree  without  displacing  segments  from  the 
calling  tree.  Routines  that  are  called  from  sove.al  main  tree  overlay 
segments,  for  example,  can  overlay  one  another  in  a  co-tree.  The  same 
considerations  in  deciding  whether  to  create  memory-resident  overlays 
or  disk-resident  overlays  in  a  single-tree  structure  apply  in  building 
a  structure  containing  co-trees. 


3.5.1   Defining  a  Multiple-Tree  Structure 

Multiple-tree  structures  are  specified  within  the  Overlay  Description 
Language  by  extending  the  function  of  the  comma  operator.  As 
described  in  Section  3.4,  this  operator,  when  ''ncluded  within 
parentheses,  defines  a  pair  of  segments  that  share  storage.  Including 
the  comma  operator  outside  all  parentheses  delimits  overlay  trees. 
The  first  overlay  tree  thus  defined  is  the  main  tree.  Subsequent 
trees  are  co-trees.   For  example: 


.ROOT 

X,Y 

X: 

.FCTR 

X0-(X1,X2,X3) 

Y: 

.FCTR 
.END 

Y0-(Y1,Y2) 
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In  this  oxample,  two  overlay  trees  are   npjclfled:    1)   a  main  trea 

containing   the   root  segment  XO  and  three  overlay  segments;   and  2)  a 

co-tree  consisting  of  root  segment  YO  and  two  overlay   segments.  The 
Executive   loads   segment   XO   into  memory  when  the  task  is  activated. 

The  task  then  loads   the   remaining   segments   through  calls   to  the 
overlay  run-time  routines. 


3.5.1.1  Defining  Co-trees  With  a  Null  Root  by  Using  .NAME  -  A  co-tree 

must  have  a  root  segment  to  establish  linkage  with  its  own  overlay 
segments.  However,  co-tree  root  segments  need  not  contain  code  or 
data  and,  therefore,  can  be  0  length.  You  can  create  a  segment  of 
this  type,  called  a  null  segment,  by  means  of  the  .NAME  directive. 
The  previous  example  is  modified,  as  shown  below,  to  move  file  YO.OBJ 
to  the  root  and  include  a   null  segment. 


.ROOT 

X,Y 

Xt 

.FCTR 

XO-YO-  (Xl,X2,X3) 

.NAME 

YNUL 

YJ 

.FCTR 
.END 

YNUL-(Y1,Y2) 

The  null  segment  YNUL  is  created  by  using   the   .NAME  directive,   and 
replaces  the  co-tree  root  that  formerly  contained  YO.OB.i, 


3.5.2  Multiple-Tree  Example 

The  following  example  illustrates  the  use  of  multiple  trees  to  reduce 
the  size  v^f  the  task. 

In  this  example,  the  root  segment  CNTRL  of  task  TKl  (described  in 
Section  3.1.1)  ha'^  had  two  routines  added  to  it:  CNTRLX  and  CNTRLY. 
The  routines  are  logically  independent  of  each  other,  and  both  are 
approximately  4000(octal)  bytes  long.  However,  the  routines  have  been 
placed  in  the  root  segment  of  TKl  instead  of  being  overlaid  because 
both  routines  must  be  accessed  from  modules  on  all  paths  of  t.ie  tree. 
In  a  single-tree  overlay  structure,  the  root  segment  is  the  only 
segment  common  to  all  paths  of  the  tree.  The  schematic  diagram  for 
the  modified  structure  is  shown  in  Figure  3-14. 

A21        A22 


A1        A2  B1        B2 


AO  BO 


CNTRLY 

I 

CNTRLX 

I 
CNTRL 


ROOT 
SEGMENT 


ZK.407-B1 

Figure  3-14   Overlay  Tree  for  Modified  TKl 
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One  possible  overlay  description  for  this  structure  is  shown  below: 

. ROOT  CNTRL-CNTRLX-CNTRLY- ( AFCTR , BFCTR , C) 
AFCTR:   .FCTR  AO- ( Al , A2FCTR) 
A2FCTR:  .FCTR  A2-(A21,A22) 
BFCTR:   .FCTR  B0-(B1,B2) 

.END 

Because  TKl  consists  of  disk-resident  overlays  and  the  new  routines 
are  concatenated  within  the  overlay  structure,  the  new  routines  add 
lOOOO(octal)  bytes  to  both  the  virtual  address  space  and  physical 
memory  requirements  of  the  task.  However,  the  added  routines  consume 
more  victual  address  space  than  might  be  expected,  as  shown  in  Figure 
3-15. 

The  expansion  of  TKl'a  virtual  address  space  requirements  caused  the 
task  to  extend  4000(octal)  bytes  beyond  the  next  highest  4K-word 
boundary  (APR  2).  Because  the  Executive  must  use  an  additional 
mapping  register  {APR2) ,  the  apparent  cost  in  virtual  address  space 
above  APR  2  of  4000(octal)  bytes  is  in  fact  20000(octal)  bytes. 
(Compare  the  diagram  in  Figure  3-15  with  the  diagram  in  Figure  3-3.) 
The  shaded  portion  of  the  unused  virtual  address  space  in  Figure  3-15 
represents  the  portion  of  virtual  address  space  that  ia  allocated  but 
is  unusable  as  allocated. 


Small  tasks,  such  as  TKl,  are  seldom  adversely  affected  by  the 
inefficient  allocation  of  virtual  address  space,  but  larger  tasks  may 
be.  For  example,  a  large  task  that  contains  code  to  create  dynamic 
regions  (see  Chapter  5)  or  that  contains  Executive  directives  to 
extend  its  task  region  (see  the  RSX-IIM/M-PLUS  Executive  Reference 
Manual)  requires  at  least  4K  words  of  virtual  address  space  to  map 
each  region.   In  such  a  task,  using  co-trees  can   often   save   virtual 


address  space  and  can,  therefore,  be  of  paramount  importance, 
be  modified  to  reflect  this. 


TKl  can 


As  noted  earlier,  the  routines  CNTRLX  and  CNTRLY  are  logically 
independent.  Logical  independence  is  a  primary  requirement  for  all 
segments  that  overlay  each  other.  However,  CNTRLX  and  CN'.  "LY  cannot 
be  structured  into  either  of  the  main  branches  of  TKl's  tree  because 
it  is  further  required  that  the  routines  be  accessible  from  modules  on 
all  paths  of  the  tree.  Therefore,  the  only  way  CNTRLX  and  CNTRLY  can 
be  overlaid  and  still  meet  all  of  these  requirements  is  through  a 
co-tree  structure.  Figure  3-16  shows  the  schematic  representation  of 
TKl  as  a  co-tree  structure. 

The  root  segment  CNTRL''  of  the  co-tree  ia  a  null  seoment.  It  contains 
no  code  or  data  and  has  a  length  of  0.  As  noted  earlier,  the  Task 
Builder  requires  the  root  segment  in  order  to  establish  linkage  with 
the  overlay  segments.  One  possible  overlay  desc  - ption  Cor  builoing 
TKl  as  a  2-tree  structure  is  shown  below. 


.NAME 

•  ROOT 

AFCTR: 

.FCTR 

A2FCTR: 

•  FCTR 

BFCTR: 

.FCTR 

.END 

CNTRL2 

CNTRL- (AFCTR, BFCTR, C) ,CNTRL2- (CNTRLX , CNTRLY) 

A0-(A1,A2FCTR) 

A2- (A21,A22) 

B0-(B1,B2) 


You  define  the  co-tree  in  the  .ROOT  directive  by  "lacing  the  comma 
operator  outside  all  parentheses  (immediately  before  CNTF,L2)  .  The 
.NAME  directive  creates  the  null  root  segment.  Figure  3-16  shows  the 
new  relationship  between  virtual  address  space  and  p  lysical  memory. 
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Figur^  3-15   Virtual  Address  Space  and  Physical  Memory 

for  Modified  TKl 
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Figure  3-16   Overlay  Co-Tree  for  Modified  TKl 

The  diagrams  in  Figure  3-17  illustiate  the  savings  (4000(octal)  bytes) 
in  both  virtual  address  space  and  physical  memory  that  is  realized  by 
overlaying  CNTRLX  and  CNTRLY.  What  may  be  more  important  in  soma 
applications,  however,  is  that  the  top  of  TKl ' s  task  region  has 
dropped  below  the  4K-word  boundary  of  APR  2.  TKl  has  gained  4K  words 
of  potentially  usable  virtual  address  space. 

NOTE 

The  numbers  used  in  this  example  have 
been  simplified  for  illustrative 
purposes.  in  addition,  the  storage 
required  for  overhead  in  handling  the 
overlay  structui.es  is  not  reflected  in 
this  example. 

Because  the  null  root  CNTRL2  is  0  bytes  long,  it  does  not  require  any 
virtual  address  space  or  phyiical  memory  and,  therefore,  does  not 
appear  in  the  diagrams  in  Figure  3-17. 

Finally,  you  can  define  any  number  of  co-trees.  Additional  co-trees 
can  access  all  modules  in  the  main  tree  and  other  co-trees. 
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Figure  3-17   Virtual  Address  Space 
and  physical  Memory  for  TKl  As  a  Co-Tree 


3.6   CREATING  AN  DDL  FiLE  FROM   A   VIRTDAL   ADDRESS   SPACE   ALLOCATION 
DIAGRAM 

You  can  use  a  graphic  method  as  an  aid  to  converting  a  virtual  address 
space  allocation  diagram  into  the  correct  Task  Builder  DDL  file. 
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First  create  a  vlrtu.il  address  space  allocation  diagram  of  your 
overlaid  task,  similar  to  that  shown  in  Fiyuro  3-18,  without  the 
dotted-line  path  shown  in  the  diagram. 


Ai 


A21 


A2i! 


A2 


AO 


B1 


B2 


BO 


ROOT  (CNTRL) 


Figure  3-18   Virtual  Address  Space  Allocation  Diagram 

The  dotted-line  path  will  be  the  basis  for  writing  the  DDL  statements 
that  you  need.  To  determine  the  path  through  your  virtual  address 
space  allocation  diagram,  follow  these  steps: 

1.  Start  ia  the  lower  left  corner  of  the  root  segment. 

2.  Draw  a  dotted  line  upward  as  far  as  you  can  go  without 
passing  through  the  top  or  into  "empty"  virtual  space, 
crossing  into  new  segments  as  needed. 

3.  When  you  reach  the  top  segment,  proceed  to  the  right  until 
you  reach  a  vertical  line. 

4.  If  the  end  of  your  dotted  line  is  now  oppositj  tiie  vertical 
line  of  the  lowest  segment,  cmss  the  vertical  line  anri 
continue  again  from  step  2;   otherwise,  proce«^d  to  i.tcp  5. 

5.  Because  the  end  of  your  dotted  line  is  not  opposite  the 
vertical  line  of  the  lowest  segment  proceed  downward  until 
you  reach  the  lowest  segment. 

6.  If  you  are  not  in  the  root,  cross  the  vertical  line  to  the 
Light  and  continue  from  step  2;  otherwise,  proceed  to  step 
7. 

7.  If  your  dotted  line  is  in  the  lower  right  corner  of  the  root, 
you  have  finished  the  dotted-line  walk. 
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Once  you  have  drawn  the  dotted  line,  you  should  go  back  over  it  to 
verify  that  you  followed  all  the  steps,  While  doing  this,  draw 
arrowheads  at  each  point  wnere  a  line  was  crossed  to  indicate  the 
direction  of  the  line. 


3.6.1  Creating  a  .RC  <T  Statement  by  Using   a  Virtual   Address   Space 
Allocation  Diagram 

Now  you  are  ready  to  write  the  .ROOT  statement.   Follow  these  steps: 

1.  Write  .ROOT  followed  by  the  name  of  the  root  s*-atement  (in 
this  excmple,  .ROOT  CNTRL) . 

2.  Follow  the  dotted-line  path. 

3.  Add  each  successive  ODL  element  to  your  root  st.-.tement,  using 
the  following  syntax,  based  on  the  direction  of  your  dotted 
1  ine . 

A.  At  an  upward  crossing:   -("name  of  new  segment" 

B.  At  a  horizontal  crossing:   ,"name  ,J  new  segment" 

C.  At  a  downward  crossing:   ; 

4.  When  you  have  returned  to  the  root,  your  root  statement  is 
complete . 

Using  the  dotted-line  path  in  Figure  3-18   and   the   above   associated 
steps  for  writing  the  .ROOT  statement,  you  can  write  as  shown  below: 


1.  Step  1 

2.  Step  3A 

3.  Step  3A 

4.  Step  3B 

5.  Step  3A 

6.  Step  38 

7.  Step  30 

8.  Step  3C 

9.  Step  3B 

10.  Step  3A 

11.  Step  3B 

12.  Step  30 

13.  Step  38 

14.  Step  30 


Write  .ROOT  ONTRL 

Write  .ROOT  ONTRL- (AO 

Write  .ROOT  ONTRL- (AO- (Al 

Write  .ROOT  ONTRL- (AO- (A1,A2 

Write  .ROOT  CNTRL- (AO- (Al ,A2- (A21 

Write  .ROOT  ONTRL- ( AO- ( Al , A2- ( A2 1 , A2 2 

Write  .ROOT  CNTRL-(AO- (A1,A2-(A21,A22) 

Write  .ROOT  ONTRL-(A0- (A1,A2-(A21,A22) ) 

write  .ROOT  ONTRL- (AO- (Al ,A2- (A21 ,A22) ) ,80 

Wri'-e  .ROOT  ONTRL-(A0- (A1,A2-(A21,A22)  ) -8C- (81 

Write  .ROOT  ONTRL- ( AO- ( Al , A2- ( A21 , A22 ) ) -80- ( 81 ,B2 

Write  .ROOT  ONTRL- (AO- (A1,A2- (A21,A22) )-B0-(81,B2) 

Write  .ROOT  ONTRL-(A0- (A1,A2-(A21,A22) ) -80- (Bl,82; ,0 

Write  .ROOT  ONTRL- (A0-(A1,A2-(A21,A22) ) -BO- (81,B2) ,0) 


The  steps  for  writing  .FCTR  statem-^nts  and  co-tree   statements   follow 
next . 
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3.6.2   Creating  a  .FCTR  Statement  by  Using   a  Virtual   Address   Space 
Allocation  Diagram 

By  using  the  steps  for  creating  a  .ROOT  statement  from  a  virtual 
address  space  allocation  diagram,  you  created  the  following  .ROOT 
statement-  . 

.ROOT  CNTRL-(A0-(A1,A2-(A21,A22) )-B0-(Bl,B2) ,C) 

It  may  be  desirable  to  simplify  your  specific  .ROOT  statement  into  one 
or  more  .FCTR  statements.  A  technique  similar  to  the  one  used  to 
create  the  .ROOT  statement  may  be  used  to  create  the  .FCTR  statement. 

In  this  example,  segment.s  AO ,  Al ,  A2 ,  A21,  and  A22  are  selected  to  be 
in  the  .FCTR  statement.  Having  selected  these  segments  (normally 
related  as  a  "stack"  of  segments)  you  are  now  ready  to  write  down  the 
.FCTR  statement. 

First,  draw  a  virtual  address  space  allocation  diagram  of  the  segments 
that  you  have  3elected.  (You  may  use  Figure  3-18  for  this 
explanation.)  Then  follow  these  next  steps  to  draw  a  dotted-line  path 
through  the  diagram: 

1.  Start  in  the  lower  left  corner  of  the  lowest  or  "base" 
segment  (AO)  in  your  diagram. 

2.  Draw  a  dotted  line  upward  as  far  as  you  can  go  without 
passing  through  the  top  or  into  empty  virtual  space,  crossing 
into  new  segments  as  needed. 

3.  When  you  reach  the  top  segment,  proceed  to  the  right  until 
you  reach  a  vertical  line. 

4.  If  the  end  of  your  dotted  line  is  now  opposite  the  vertical 
line  of  the  lowest  segment,  cross  the  vertical  line  and 
continue  again  from  step  2;   otherwise,  proceed  to  step  5. 

5.  Because  the  end  of  your  dotted  line  is  not  opposite  the 
vertical  line  of  the  lowest  segment,  proceed  downward  until 
you  reach  the  lowest  segment. 

6.  If  you  are  not  in  the  base  segment  (AO)  ,  cross  the  vertical 
line  to  the  right  and  continue  from  step  2;  otherwise, 
proceed  to  step  7 . 

7.  If  your  dotted  line  is  in  the  lower  right  corner  of  the  base 
segment,  you  have  finished  the  dotted-line  walk. 

Once  you  have  drawn  the  dotted  line,  you  should  go  back  over  it  to 
verify  that  you  followed  all  the  steps.  While  doing  this,  draw 
arrowheads  at  each  point  where  a  line  was  crossed  to  indicate  the 
direction  of  the  line. 

Now  you  are  ready  to  write  the  .FCTR  statement.  Follow  these  next 
steps: 

1.  Write  a  label  followed  by  .FCTR,  which  is  in  turn  followed  by 
the  name  of  the  first  segment  (AO)  (in  this  example,  AFCTR 
.FCTR  AO) 

2.  Follow  the  dotted-line  path. 
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3.  Add  each  successive  ODL  element  to  your  root  statement,  using 
the  following  syntax,  Lased  on  the  direction  of  your  dotted 
line. 

A.  At  an  upward  crossing:   ("name  of  new  segment" 

B.  At  a  horizontal  crossing:   ,"name  of  new  segment" 

C.  At  a  downward  crossing:   ) 

4.  When  you  have  returned  to  the  base  segment,  your  .FCTR 
statement  is  complete. 

Using  the  dotted  line  path  and  the  above  associated  steps  for  writing 
the  .FCTR  statement,  you  can  write  as  shown  below: 

1.  Step  1  :  Write  AFCTR  .FCTR  AO 

2.  Step  3A:  Write  AFCTR  .FCTR  A0-(A1 

3.  Step  3B:  Write  AFCTR  .FCTR  A0-(A1,A2 

4.  Step  3A:  Write  AFCTR  .FCTR  AO- ( Al ,A2- (A21 

5.  Step  3B:  Write  AFCTR  .FCTR  AO- { Al , A2- ( A21 , A22 

6.  Step  3C:  Write  AFCTR  .FCTR  AO- ( Al ,A2- ( A21 , A22) 

7.  Step  3C:  Write  AFCTR  .FCTR  AO- { Al , A2- ( A21 , A22 ) ) 

You  have  now  reached  the  base  segment  and  have  written  the  two  ODL 
statements : 

.ROOT  CNTRL-(A0-(A1,A2-(A21,A22) )-B0-(Bl,B2) ,C) 
AFCTR:   .FCTR  AO- ( Al , A2- ( A21 , A22 ) ) 

The  last  step  requires  that  you  substitute  the  label,  AFCTR,  into  the 
.ROOT  statement,  which  results  in: 

.ROOT  CNTRL-AFCTR-BO- (B1,B2) ,C) 
AFCTR:   .FCTR  AO- ( Al , A2- ( A21 , A22 ) ) 

Additional  .FCTR  statements  would  be  determined  and  written  in  the 
same  way.  For  example,  you  could  write  a  .FCTR  statement  labeled 
BFCTR  for  the  segments  BO,  Bl ,  and  B2 . 

The  following  section  shows  how  to  write  an  ODL  statement  for  a 
co-tree  by  using  the  same  methods. 


3.6.3   Creating  an  ODL  Statement  for  a   Co-Tree   by   Using   a   Virtual 
Address  Space  Diagram 

Assuming  that  you  want  to  write  an  ODL  statement  for  a  co-tree  like 
the  one  in  Figure  3-19,  you  would  ha'e  vo  virtual  address  space 
allocation  diagrams,  one  for  the  main  tree  and  one  for  the  co-tree. 
These  two  diagrams  are  shown  in  Figure  3-19. 
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Figure  3-19   Virtual  Address  Space  Allocation  for  a  Main  Tree 

and  Its  Co-Tree 


From  Figure  3-19  you  see  that  the  co-tree  is  a  stack  of  segments  also. 
Therefore,  it  is  possible  to  write  the  statement  for  the  co-tree  in 
the  same  fashion  and  with  the  same  rules  as  that  described  in  Section 
3.6.   Hov.'e7er,  certain  facts  must  be  kept  in  mind.   These  are  that: 

•  The  co-tree  has  a  null  root 

•  A  .NAMF  statement  must  bt.  used  to    name  the  null  root 

•  A  comma  must  be  placed  outside  of  the  parentheses  and  at  the 
end  of  that  part  of  the  .ROOT  statement  that  defines  the  main 
tree 

Therefore,  the  ODL  statement  that  we  obtain  before  writing  the  co-tree 
part  is: 

.NAME  CNTRL2 

.ROOT  CNTRL-AFCTR-BO- (B1,B2) ,C) , 
AFCTR:   .FCTR  AO- ( Al , A2- ( A21 , A22 ) ) 

By  following  the  rules  in  Section  3.6  and  by  using  the  diagram  in 
Figure  3-19,  you  can  then  create  the  ODL  statement: 

.NAME  CNTRL2 

.ROOT  CNTRL~AFCTR-B0-(B1,B2) ,CNTRL2 - (CNTRLX , CNTRLY) 
AFCTR:   .FCTR  A0-(A1,A2-(A21,A22) ) 


3.7   OVERLAYING  PROGRAMS  WRITTEN  IN  A  HIGH-LEVEL  LANGUAGE 

Programs  written  in  a  high-level  language  usually  require  the  use  of  a 
large  number  of  library  routines  in  order  to  execute.  Unless  care  is 
taken  when  overlaying  such  programs,  the  following  problems  r-an   occur: 

•   TKB  throughput  may   be   drastically   reduced   because   of   the 
number  of  library  references  in  each  overlay  segment. 
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•  Library  references  from  the  default  object  module  library  that 
are  resolved  across  tree  boundaries  can  rejult  in 
unintentional  displacement  of  segments  from  memory  at  lun 
time. 

•  Attempts  to  task-build  sue':  progra.ns  can  result  in  multiple 
and  ambiguous  symbol  definitions  when  a  co-tree  structure  is 
defined. 

The  following  procedures  are  effective  in  solving  these  problems: 

•  You  can  increase  TKB  throughput  by  linking  commonly  used 
library  routines  into  the  main  root  segment. 

•  You  can  eliminate  ambiguous  definitions,  multiple  definitions, 
and  cross-tree  references  by  using  the  NOFU  switch  (the  TKB 
default)  to  restrict  the  scope  of  the  default  lib  .a-/  search. 
However,  restricting  the  scope  of  the  default  library  search 
may  also  cause  problems. 

If  sufficient  memory  is  available,  you  can  effectively  place  the 
object  time  system  in  the  root  segment  by  building  a  memory-resident 
library.  This  also  reduces  total  system  memory  requirements  if  other 
tasks  are  also  currently  using  the  library. 

If  a  memory-resident  library  canrn^t  be  built,  you  can  force  library 
modules  into  the  root  by  preparing  a  list  of  the  appropriate  global 
references  and  linking  the  object  module  into  the  root  segment. 

For  other  ways  to  reduce  task  size,  you  should  consult  the  user's 
guide  for  the  language  you  are  using. 


3.8   EXANPLE  3-1:   BUILDING  AN  OVERLAY 

The  text  in  this  section  and  the  figures  associated  with  it  illustrate 
the  building  of  an  overlay  structure.  For  this  example,  the  routines 
of  the  resident  library  LIB.TSK  and  the  task  that  refers  to  it, 
MAIN.TSK  (from  Example  5-3,  Chapter  5),  are  assembled  as  separate 
modules  and  built  as  an  overlaid  task.  This  task  is  built  first  with 
disk-resident  overlays  ""nd  then  with  memory-resident  overlays.  The 
disk-resident  version  of  the  task  is  named  OVR.TSK  and  the 
memory-resident  version  is  named  RESOVR.TSK. 

NOTE 

This  example  is  intended  to  provide  you 
with  a  working  illustration  of  the 
Overlay  Description  Language.  It  does 
not  reflect  the  most  efficient  use  of 
it. 

Two  alterations  were  made  to  each  of  the  routines  for  this  example: 

•   A  .TITLE  and   .END   assembler   directive   was   added   to   each 
routine  to  establish  it  as  a  unique  module. 
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•  The  following  ass«>mbler  directive  was  added  to  each  arithmetic 
routine  to  increase  its  allocation: 

.BLKW  1024. *3 

This  was  done  to  make  TKB  allocation   of   address   space  more 
obvious  for  documentation  purposes. 

The  operation  of  the  overlaid  task  is  identical  to  that  of  Example  5-3 
in  Chapter  5.  The  routines  and  their  titles  as  a  result  of  the  .TITLE 
directives  are  as  follows: 

•  The  integer  addition  routine  is  named  ADDOV. 

•  The  integer  subtraction  routine  is  named  SUBOV. 

•  The  integer  nultipl ication  routine  is  named  MULOV. 

•  The  integer  livision  routine  is  named  DIVOV. 

•  The  register  save  and  restore  routine  is  named  SAVOV. 

•  The  print  routine  is  named  PRNOV. 

•  The  main  calling  rout. ne  is  named  ROOTM, 
The  lengths  of  the  modules  are: 

Module  Length  (in  Octal) 

ADDOV  14024  bytes 

SUBOV  14024  bytes 

MULOV  14024  bytes 

DIVOV  14026  bytes 

SAVOV  4042  bytes 

PRNOV  4260  bytes 

ROOTM  4104  bytes 
The  flow  of  control  for  OVR.TSK  is  as  follows: 

1.  ROOTM  calls  ADDOV  and  ADDOV  returns  to  ROOTM, 

2.  ROOTM  calls  PRNOV  to  print  the  result  and   PRNOV   returns   to 
ROOTM. 

3.  ROOTM  calls  SUBOV  and  SUBOV  returns  to  ROOTM. 

4.  ROOTM  calls  PRNOV  to  print  the  result  and   PRNOV   returns   to 
ROOTM. 

5.  ROOTM  calls  DIVOV  and  DIVOV  returns  to  lOOTM. 

6.  ROOTM  calls  PRNOV  to  print  the  result  and   PRNOV   returns   to 
ROOTM. 
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7.  ROOTM  calls  MULOV  and  MULOV  returns  to  ROOTM. 

8.  ROOTM  calls  PRNOV  to  print  the  result  and   PRNOV   returns   to 
ROOTM. 

The  print  routine  (contained  in  module  PRNOV)  is  called  between  each 
arithmetic  operation  by  the  control  routine  (contained  in  module 
ROOTM).  To  avoid  loading  it  into  physical  memory  each  time  it  is 
called,  you  can  place  PRNOV  in  the  root  segment  of  the  tas)<.  In 
additiCi'',  each  arithmetic  routine  calls  SAVOV.  Therefore,  SAVOV  must 
be  on  a  path  common  to  all  segments  in  the  tree.  It  too  is  placed  in 
the  root  segment  of  the  taslt.  One  possible  overlay  configuration  for 
this  task  is  shown  in  Figure  3-20. 

SUBOV  DIVOV 


MULOV  ADDOV 

I 


1 

SAVOV 


I 


PRNOV   ^  SEGMENT 
ROOTM 


Figure  3-20   Overlay  Tree  of  Virtual  Address  Space  for  OVR.TSK 

To  build  this  overlay,  first  create  an  ODL  file  (OVERTREE. ODL)  that 
contains  its  description: 

.  ROOT    ROOTM-PRNOV-SAVOV-*  (MULOV  ,  ADDOV-  (S'JBOV,  DIVOV)  ) 

.END 

Then,  after  you  have  modified  the  nodules  and  assembled  them,  you  can 
build  the  task  with  the  following  command  line: 

TKB>  '-)V1<,0VK/-SP  =  0VRTREE/MP 

This  command  instructs  TKB  to  build  a  task  image,  OVR.TSK,  and  to 
create  a  map  file,  OVR.MAP,  under  the  UFD  that  corresponds  to  th>> 
terminal  'JIC.  The  negated  spool  switch  (/-SP)  inhibits  TKB  froit, 
spooling  the  map  file  to  the  line  printer. 

The  overlay  switch  (/MP)  attached  to  the  input  file  tells  TKB  that  t.ie 

input   file   is   an   ODL   file.   Therefore,  this  file  will  be  the  onli 

input  file  specified.  Refer  to  Chapter  10  for  a  description  of  the 
switches  used  in  this  exami-^le. 

A  portion  of  the  map  that  results  from  this  task  build  is  shown  in 
Example  3-1. 
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Example   3-1      Map   File    for    OVR.TSK 


OVR.TSK  Memory   allocation   map      TKB   M40.10 

Ol-JAN-82    10:06 


Page  1 


Partition  name 
Identl f icat ion 
Task   V.IC 
Stack     limitJ 
PRG  xfr  address 
Total  address  windows 
Task   image   size 
Task  address  limits 
R-W  disk  blk  limits 


GEN 

01 

[7,621 

000260  001257  001000  00512, 

001264 

1. 

7488.   words 

000000  035107 

000002  000073  000072  00058, 


OVR.TSK  Overlay  description: 
Base    Top        Length 

-—    0--     ®      

000000  I  005033  I  005034   02588. 

005034   021O'i7   014024   06164. 

005034   021057 

021060 

021060 


035103 
0-',5107 


^ 


014024  06164. 
014024  06164. 
014030   06168. 


ROOTM 


MULOV 
ADDOV 


SUBOV 
DIVOV 


***  Root  segment:   ROOTM 

R/W  mem   limits:  000000  005033  005034  02588, 
Disk  blk  limits:  000002  000007  000006  00006, 

Memory  allocation  synopsis: 

Section 


Title   Ident   File 


.  BLK. : (RW,I,LCL,REL,CON)  001260  002514  01356 

001260  000102  00066 
001362  000260  00176 
001642  000042  00034 

ANS    : (RW,D,GBL,REL,OVR)  003774  000002  00002 

003774  000002  00002.  ROOTM 


ROOTM  01 
PRNOV  01 
SAVOV   01 


01 


003774  000002  00002.  PRNOV   01 


ROOTM . OBJ ; 1 
PRNOV. OBJ; 1 
SAV0V.0BJ;1 

ROOTM. OBJ ;1 
PRNOV. OBJ ;1 


Global  symbols: 


AADD    004032-R   DIVV    004052-R   PRINT   001550-R   SUBB 
MULL    004022-R   SAVAL   001642-R 


004042-R 


Total  work  file  references 

:  6863 

Work   file   reads: 

0. 

Work   file  writes: 

0. 

Size  of  core  pool: 

7086. 

words 

(27. 

pages) 

Size  of  work  file: 

3072. 

words 

(12. 

pages) 

Elapsed  time:00 :00 : 14 


# 
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Figure  3-21  shows  the  allocation  of  virtual  address  space  for  OVR.TSK. 
The  circled  numbers  in  Example  3-1  correspond  to  those  in  Figure  3-2.1. 

Note  that  the  root  segment  for  OVR.TSK  (ROOTM)  has  expanded  with  task 
building  while  the  segments  containing  the  arithmetic  routines  have 
not.  Before  task  building,  the  sum  of  the  modules  (in  octal  bytes) 
that  comprise  the  root  segment  is: 

4104  +  4260  +  4042  =  14,426  bytes 

After  task  building,  the  root  segment  is  20 ,677 (octal )  bytes  long. 
TKB  has  auded  a  header,  a  stack  area,  and  the  overlay  run-time 
routines  to  it.  The  segments  containing  the  arithmetic  routines  have 
not  chcnged.  If  there  had  been  calls  from  segments  nearer  the  root  to 
segments  farther  up  the  tree,  the  Task  Builder  would  have  added  data 
structures  to  the  calling  segments  as  well.  (Refer  to  Chapter  4  for  a 
description  of  the  overlay  loading  methods.) 

You  can  build  OVR  as  a  memory-resident  overlay  by  simply  adding  the 
memory-resident  operator  (!)  to  the  ODL  file  for  OVR  as  shown  below: 

•ROOT    ROOTM-PRNOV-SAVOV-* ! (MULOV , ADDOV- ! (SUBOV, DIVOV) ) 
.END 

For  this  example,  the  name  of  the  ODL  file  and  the  task  image  file 
have  been  changed  to  RESOVR.ODL  to  distinguish  it  from  the 
disk-resident  version.  You  can  build  RESOVR  with  the  following 
command  line: 

TKB>  RESOVR, RESOVR/-SP=RESOVR/MP 

This  command  directs  TKB  to  build  a  task  named  RESOVR. TSK  and  to 
create  a  map  file  named  RESOVR. MAP.  The  negated  spooling  switch 
(/-SP)  inhibits  spooling  of  the  map  file. 

The  /MP  switch  on  the  input  file  tells  TKB  that  the  file  is  an  ODL 
file  and  that  it  will  be  the  only  input  file  for  this  task  build. 
Refer  to  Chapter  10  for  a  description  of  the  switches  used  in  this 
example . 

A  portion  of  the  map  that  results  from  this  task  build  is  shown  in 
Example  3-2. 

Figure  3-1"  shows  the  allocation  of  virtual  address  space  for 
RESOVR. TSK.  The  circled  numbers  in  Example  3-2  correspond  to  those  in 
Figure  3-22. 
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160000  APR  7 


140000  APR  6 


120000  APR  5 


100000  APR  4- 


60000  APR  3- 


40000  APR  2- 


20000  APR  1- 


0  APR  0- 


UNUSED 


MULOV 


SUBOV 


DIVOV 


ADDOV 


SYSLIB 
SAVOV 
PRNOV 
ROOTM 


HEADER  AND  STACK 


035107 


^ 


021057 


005033 


ROOT  SEGMENT 


-  001257 
~-  000000 


^ 


Figure  3-21   Allocation  of  Virtual  Address  Space  for  OVR.TSK 
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Example  3-2   Map  File  for  RESOVR.TSK 


Partition  name 
Identi  f ication 
Task   UIC 
Stack     limits 
PRG  xfr  address 


GEN 

01 

[7,62] 

000320  001317  001000  00512. 

001324 


V 
Total  address  windows:  3.  © 
Task  image  size  :  13920.  words 
Task  address  limits:  000000  057777 
R-W  disk  blk  limits:  000003  000074  000072  00058, 


RESOVR.TSK  Overlay  description; 
Base    Top        Length 

O  --     0      

000000  I  005677  I  005700   03008. 
OJOJD^OO   034077   014100   06208. 
014100   06208. 


020000 
040000 


040000 


034077 
054077 
054077 


014100 
014100 


GO       O0 


06208. 
06208. 


ROOTM 


MULOV 
ADDOV 


SUBOV 
DIVOV 


***  Root  segment:  ROOTM 

R/W  mem   limits:  000000  005677  005700  03008. 
Disk  blk  limits:  000003  000010  000006  00006. 


Memory  allocation  synopsis: 
Section 


BLK. : (RW, I , LCL , REL ,CON) 


ANS 


(RW,D,GBL,REL,OVR) 


001320  002514  01356, 

001320  000102  00066. 

001422  000260  00176. 

001702  000042  00034, 

004034  000002  00002. 

004034  000002  00002. 

004034  000002  00002. 


Title   Ident   File 


ROOTM 
PRNOV 
SAVOV 

ROOTM 
PRNOV 


01 
01 
01 

01 
01 


ROOTM. OBJ; 1 
PRNOV. OBJ; 1 
SAVOV.OBJ;! 

ROOTM. OBJ ;1 
PRN0V.0BJ;1 


Global  symbols; 


AADD 
MULL 


004072-R 
004062-R 


DIVV 
SAVAL 


004112-R 
001702-R 


PRINT   001610-R   SUBB 


004102-R 


***  Task  builder  statistics: 

Total  work  file  references:   6938, 

Work  file  reads   :  0. 

Work  file  writes  :   0. 

Size  of  core  pool:   4178.   words 

Size  of  work  file:   3072.   words 


Elapsed  time:00 :00 : 21 


(16, 
(12, 


pages) 
pages) 


3-47 


OVERLAY  CAPABILITY 


Note  that  TKB  allocates   virtual   address   space   for  each   level   of 

overlay   segment  on  a  4K-word  boundary.   When  built  as  a  disk-resident 

overlay,  this  structure  requires  12K  words  of  virtual  address   space; 

when   built   as   a   memory-resident  overlay  structure,  it  requires  16K 

words  of  virtual  address  space.   As  noted  earlier,  you  must  be  careful 

when   using   memory-resident   overlays   to  ensure  that  virtual  address 
space  is  used  efficiently. 


160000    APR  7 


140000    APR  6- 


120000    APR  5 


100000    APR  4 


60000    APR  3- 


40000    APR  2 


20000 


APR  1- 


APR  0- 


^^"Mnwnn***^!^ 


WfP^BWWWWWH 


UNUSED 


SYSLIB 
SAVOV 
PRNOV 
ROOTM 


HEADER  AND  STACK 


054077 


-  020000 


ROOT  SEGME-)T 


Figure  3-22   Allocation  of  virtual  Address  Space  for  RESOVR.TSK 
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Finally,  note  in  Figure  3-22  that  TKB  has  allocated  three  window 
blocks  to  map  RESOVR.TSK.  Each  level  of  the  overlay  in  a 
memory-resident  overlay  requires  a  separate  window  block  to  map  it. 
In  a  disk-  resident  overlay,  a  single  window  block  maps  the  entire 
structure  regardless  of  how  many  segment  luvels  there  are  within  the 
structure.  This  consideration  can  be  important  when  you  are  building 
an  overlaid  task  that  either  creates  dynamic  regions  or  accesses  a 
resident  library  or  common,  because  of  the  extra  window  blocks 
required  to  use  these  features. 


3.9   SUMMARY  OF  THE  OVERLAY  DESCRIPTION  LANGUAGE 


An  overlay  structure  consists  of  one  or  more  trees.  Each  tree 
contains  at  least  one  segment.  A  segment  is  one  or  more 
modules  containing  one  or  more  program  sections  that  can  be 
loaded  by  a  single  Jisk  access. 

A  tree  can  have  only  one  root  segment,  but  it  can  have  any 
number  of  overlay  segments. 

An  ODL  file  is  a  text  file  consisting  of  a  series  of  overlay 
description  directives,  one  directive  per  line.  You  enter 
this  file  in  the  TKB  command  line,  and  identify  it  as  an  ODL 
file  by  attaching  the  MP  switch  to  the  file  name.  If  you 
enter  an  ODL  file  in  the  TKB  command  line,  it  must  be  the  only 
input  file  you  specify. 

The  Overlay  Description  Language  provides  five  directives  for 
specifying  the  tree  representation  of  the  overlay  structure: 

.ROOT  and  .END  —  There  can  be  only  one  .ROOT  and  one  .END 
directive;  the  .END  directive  must  be  the  last  directive 
because  it  terminates  input. 

.PSECT,  .FCTR,  and  .NAME  —  These  can  be  used  in  any  order 
in  the  ODL  file. 

You  define  the  tree  structure  using  the  hyphen  (-) ,  comma  (,), 
and  exclamation  point  (!)  operators,  and  by  using  parentheses. 

The  hyphen  operator  (-)  indicates  that  its  arguments  are  to 
be  concatenated  and  thus  are  to  coexist  in  memory. 

The  comma  operator  (,)  within  parentheses  indicates  that 
its  arguments  are  to  overlay  each  other  either  physically, 
if  disk  resident,  or  virtually,  if  memory  resident. 

The  comma  operator  not  within  parentheses  delimits  overlay 
trees . 

The  exclamation  point  operator  (!)  immediately  before  a 
left  parenthesis  declares  the  enclosed  segments  to  be 
memory  resident.  Nested  segments  in  parentheses  are  not 
affected  by  an  exclamation  point  operator  at  a  level  closer 
to  the  root. 
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The  parentheses  group  segments  that  begin  at  the  same  point 
in  memory.   For  example: 

.ROOT  A-B- (C,D-{E,F) ) 

This  ODL  command  line  defines  an  overlay  structure  with   a 

root   segment   consisting   of  the  modules  A  and  B.  in  this 

structure,  there  are  four  overlay  segments:   C,  D,  E,   and 

F.    The   outer   pair   of   parentheses   indicates  that  the 

overlay  segments  C  and  0  start  at  the  same  virtual  address; 
and  similarly,  the  inner  parentheses  indicate  that  E  and  F 
start  at  the  same  virtual  address. 

The  .ROOT  directive  defines  the  beginning  overlay  structure. 
The  arguments  of  the  .ROOT  directive  are  one  or  more  of  the 
fol lowi  ng : 

File  specifications  as  described  in  Chapter  1 

Factor  labels 

Segment  names 

Program-section  names 

The  .END  directive  terminates  input. 

The  .FCTR  directive  provides  a  means  for  replacing  text  by  a 
symbolic  reference  (the  factor  label) .  This  replacement  is 
useful  for  two  reasons: 

-  The  .FCTR  directive  extends  the  text  of  the  .ROOT  directive 
to  more  than  one  line  and  thus  allows  complex  trees  to  be 
represented . 

The  .FCVR  directive  allows  you  to  write  the  overlay 
description  in  a  form  that  makes  the  structure  of  the  tree 
more  apparent. 

For  example: 

.ROOT  A-(B-(C,D) ,E-(F,G) ,H) 
.END 

Using  the  .FCTR  directive,  you  can  write  this  overlay 
description  as  follows: 

.ROOT  A-(F1,F2,H) 

Fl:       .FCTR  B-(C,D) 

F2:        .FCTR  E-(F,G) 

.END 

The  second  representation  makes  it  clear  that  the  tree  has 
three  main  branches. 

The  .PSECT  directive  provides  a  means  for  directly  specifying 
the  segment  in  which  a  program  section  is  placed.  It  accepts 
the  name  of  the  program  section  and  its  attributes.  For 
example: 

.PSECT  ALPHA,CON,GBL,RW,I,REL 
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ALPHA  is  the  program  section  name  and  the  remaining  arguments 
are  the  program  section's  attributes  (program  section 
attributes  are  described  in  Chapter  2). 

The  prograiri  section  name  (composed  of  the  characters  A-Z,  0-9 » 
$,  ojc  .)  must  appear  first  in  the  .PSECT  directive,  but  the 
attributes  can  appear  in  any  order  or  can  be  omitted.  If  an 
attribute  is  omitted,  a  default  condition  is  assumed.  The 
defaults  for  program  section  attributes  are  RW,  I,  LCL,  REL, 
and  CON. 

In  the  example  above,  therefore,  you  need  only  specify  the 
attributes  that  do  not  correspond  to  the  defaults:  .PSECT 
ALPHA, GBL 

The  .NAME  directive  provides  you  with  the  means  to  designate  ci 
segment  name  for  use  in  the  overlay  description,  and  to 
specify  segment  attributes.  This  directive  is  useful  for 
creating  a  null  segment,  naming  a  segment  that  is  to  be  loaded 
manually,  or  naming  a  nonexecutable  segment  that  is  to  be 
autoloadable .  (Refer  to  Chapter  4  of  this  manual  for  a 
description  of  manually  loaded  and  automatically  loaded 
segments.)  If  y-u  do  not  use  the  .NAME  dirtjtive,  the  Task 
Builder  uses  the  name  of  the  first  file,  program  section,  or 
library  module  in  the  segment  to  identify  the  segment. 

The  .NAME  directive  creates  a  segment  name  as  follows: 

.NAME  segname,attr ,attr 

segname 

is  the  designated  name  (composed   of   the   characters   A-Z, 
0-9,  and  $) . 


attr 

is  an  optional  attr.ibute  taken  from   the   following:    GBL, 
NODSK,  NOGBL,  DSK. 

The  defaults  are  NOGBL  and  DSK.  The  defined  name  must  be 
unique  with  respect  to  the  names  of  program  sections, 
sijgments,  files,  and  factor  labels. 

You  can  define  a  co-tree  by  specifying  an  additional  tree 
structure  in  the  .ROOT  directive.  The  first  overlay  tree 
description  in  the  .ROOT  directive  is  the  main  tree. 
Subsequent  overlay  descriptions  are  co-trees.   For  example: 

.ROOT  A-B-(C,D- (E,F) ) ,X- (Y,Z) ,Q- (R,S,T) 

The  main  tree  in  this  example  has  the  root  segment  consisting 
of  files  A. OBJ  and  B.OBJ.  Two  co-trees  are  defined;  the 
first  co-tree  has  the  root  segment  X  and  the  second  co-tree 
has  the  root  segment  Q. 
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The  RSX-llM/M-PLUS  systems  provide  two  methods  for  loading 
disk-resident  and  memory-resident  overlays: 

•  Autoload  --  The  overlay  run-time  routines  are  automatically 
called  to  load  segments  you  have  specified. 

•  Manual  Load  --  You  include  in  the  task  explicit  calls  to  the 
overlay  run-time  routines. 

When  you  build  an  overlaid  task,  you  must  decide  which  one  of  these 
methods  to  use,  because  both  cannot  be  used  in  the  same  task. 

The  loading  process  depends  on  the  kind  of  overlay: 

•  Disk  resident  --  A  segment  is  loaded  from  disk  into  a  shared 
area  of  physical  memory,  writing  over  whatever  was  present. 

•  Memory  resident  --  A  segment  is  loaded  by  mapping  a  set  of 
shared  virtual  addresses  to  a  unique  unshared  area  of  physical 
memory,  where  the  segment  has  been  made  permanently  resident 
(after  having  been  initially  brought  in  from  the  disk). 

With  the  autoload  method,  the  overlay  run-time  routines  handle  loading 
and  error  recovery.  Overlays  are  automatically  loaded  by  being 
referenced  through  a  transf er-of-control  instruction  (CALL,  JMP,  or 
JSR) .   No  explicit  calls  to  the  overlay  run-time  routines  are  needed. 

In  the  manual  load  method,  you  handle  loading  and  error  recovery 
explicitly.  Manual  loading  saves  space  and  gives  you  full  cont'-ol 
over  the  loading  process,  including  the  ability  to  specify  whether 
loading  is  to  be  done  synchronously  or  asynchronously. 

In  the  manual  load  method,  yo  must  provide  for  loading  the  overlay 
segments  of  the  main  tree,  as  well  as  the  root  segments  and  the 
overlay  segments  of  the  co-trees.  Once  loaded,  the  root  segment  of  a 
co-tree  remains  in  memory. 


4  . 1   AUTOLOAD 

To  specify  the  autoload  method,  you  use  the  autoload  indicator,  an 
asterisk  (*).  You  place  this  indicator  in  the  DDL  description  of  the 
task  at  the  points  where  loading  must  occur.  The  execution  of  a 
transfer-of-control  instruction  to  an  autoloadable  segment  up-tree 
(farther  away  from  the  root)  initiates  the  autoload  process. 
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4.1.1   Autoload  Indicator 

The  autoload  indicator  (*)  marks  as  autoloadable  the  segment  or  other 
task  element  (as  defined  below).  If  you  apply  the  autoload  indicator 
to  an  DDL  statement  enclosed  in  parentheses,  every  task  element  within 
the  parentheses  is  marked  as  autoloadable.  Placing  the  autoload 
indicator  at  the  outermost  level  of  parentheses  in  the  DDL  description 
marks  every  module  in  the  overlay  segments  as  autoloadable. 

In  the  TKl  example  of  Chapter  3,  Section  3.1.1,  if  segment  C  consisted 
of  a  set  of  modules  CI,  C2,  C3,  C4 ,  and  C5,  the  tree  diagram  would  be 
as  shown  in  Figure  4-1. 
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Figure  4-1   Details  of  Segment  C  of  TKl 


Placing  the  autoload  indicator  at  the  outermost  level  of  parentheses 
ensures  that,  regardless  of  the  flow  of  control  within  the  task,  a 
module  will  be  properly  loaded  when  it  is  called.  The  DDL  description 
for  task  TKl  would  be: 

.ROOT  CNTRL-* (AFCTR,BFCTR,CFCTR) 
AFCTR:     .FCTR  AO- ( Al , A2- ( A2 1 , A22 ) ) 
BFCTR:      .FCTR  B0-(BI,B2) 
CFCTR:     .FCTR  C1-C2-C3-C4-C5 

.END 

When  you  use  autoload,  the  root  of  a  co-tree  is  loaded  by  path  loading 
if  one  of  the  branches  of  the  co-tree  is  called  before  the  root. 
However,  if  the  root  of  the  co-tree  is  called  before  the  branch  is 
called,  the  root  must  have  an  autoload  indicator. 

Also,  when  the  root  segment  of  a  co-tree  is  not  a  null  segment,  you 
must  mark  the  co-tree's  root  segment  (CNTRL2)  as  well  as  its  outermost 
level  of  parentheses  to  ensure  that  all  modules  of  the  co-tree  are 
properly  loaded.  For  example,  if  the  co-tree  root  (CNTRL2)  of  the 
multiple  tree  example,  Section  3.5.2,  had  contained  code  or  data,  it 
would  have  been  marked  as  follows: 

.ROOT  CNTRL-* (AFCTR, BFTCR, CFCTR) ,*CNTRL2-* ( CNTRLX ,CNTRLY) 


You  can  apply  the  autoload  indicator  to  the  following  elements 


•   File   names  --  to   make   all   the   components   of    the 
autoloadable . 


file 


•   Portions    of    ODL    tree    descriptions  enclosed     in 

parentheses  --  to  make  all  the  elements  within  the  parentheses 

autoloadable,    including    elements   within  any    nested 
parentheses . 
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•  Program  section  names  --  to  make  the  program  section 
autoloadable .  The  program  section  must  have  the  instruction 
(I)  attribute. 

•  Segment  names  defined  by  the  .NAME  directive  --  to  make  all 
components  of  the  segment  autoloadable. 

•  .FCTR  label  names  --  to  make  the  first  component  of  the  factor 
autoloadable.  All  elements  specified  in  the  .FCTR  statement 
are  autoloadable  if  they  are  enclosed  in  parentheses. 

In  the  following  example,  two  .fSECT  directives  and  a  .NAME  directive 
are  introduced  into  the  DDL  description  for  TKl .  Autoload  indicators 
are  applied  as  follows: 

.ROOT  CNTRL-(*AFCTR,*BFCTR,*CFCTR)  O 
AFCTR:     .FCTR  A0-* ASUB1-ASUB2-* ( Al , A2- ( A2 1 , A22  )  )  GO 
BFCTR:     .FCTR  (B0-(B1,B2)) 
CFCTR:      .FCTR  CNAM-C1-C2-C3-C4-C5 

.NAME  CNAM,GBL  O 

.PSECT  ASUBl, I,GBL,OVR  Q 

.PSECT  ASUB2, I,GBL,OVR 

.END 

The  following  notes  are  keyed  to  the  example  above. 

O  The  autoload  indicator  is  applied  to  each  factor  name; 
therefore : 

a.  *AFCTR=*AO 

b.  *BFCTR=* (BO- (B1,B2) ) 

c.  *CFCTR=*CNAM 

CNAM,  however,  is  an  element  defined  by  a  .NAME  directive. 
Therefore,  all  components  of  the  segment  to  which  the  name 
applies  are  made  autoloadable,  that  is,  CI,  C2 ,  C3 ,  C4 ,  and 
C5. 

0  The  autoload  indicator  is  applied  to  the  name  of  a  program 
section  with  the  instruction  (I)  attribute  (*ASUB1),  so  that 
program  section  ASUBl  is  made  autoloadable. 

Q  The  autoload  indicator  is  applied  to  a  portion  of  the  ODL 
description  enclosed  in  parentheses: 

* (A1,A2-(A21,A22) ) 

Thus,  every  element  within  the  parentheses  is  made 
autoloadable  (that  is,  files  Al,  A2,  A21,  and  A22). 

The  net  effect  of  this  ODL  description  is  to  make  every  element  except 
program  section  ASUB2  autoloadable. 


4.1.2   Path  Loading 

The  autoload  method  uses  path  loading;  that  is,  a  call  from  one 
segment  to  another  segment  up-tree  (farther  away  from  the  root) 
ensures  that  all  the  segments  on  the  path  from  the  calling  segment  to 
the  called  segment  will  reside  in  physical  memory  and  be  mapped.  Path 
loading  is  confined  to  the  tree  in  which  the  called   segment   resides. 
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A  call  from  a  segment  in  one  tree  to  a  segment  in  anothor  tree  results 
in  the  loading  of  all  segments  on  the  path  in  the  second  tree  from  the 
root  to  the  called  module. 

In  Figure  4-2,  if  CNTRL  calls  A22,  all  the  modules  between  the  CNTRL 
and  A2  are  loaded.   In  this  case,  modules  AO  and  A2  are  loaded. 
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Figure  4-2   Path-Loading  Example 


With  the  autoload  method,  the  overlay  run-time  routines  keep  a  record 
of  the  segments  that  are  loaded  and  mapped,  and  issue  disk-load 
requests  only  for  segments  that  are  not  in  memory.  If  CNTRL  calls  A2 
after  calling  Al,  AO  is  not  loaded  again  because  it  is  already  in 
memory  and  mapped. 

A  reference  from  one  segment  to  another  segment  down-tree  (closer  to 
the  root)  is  resolved  directly.  For  example,  A2  can  immediately 
access  AO  because  AO  was  path  loaded  in  the  call  to  A2 . 


4.1.3   Autoload  Vectors 

To  resolve  a  reference  up-tree  to  a  global  symbol  in  an   autoloadable 

segment,   TKB   generates   an  autoload  vector  for  the  referenced  global 

symbol.   The  reference  in  the  code  is  changed   to   a  definition   that 
points   to   an   autoload   vector   entry.    The  format  for  the  autoload 

vector  for  conventional  tasks  is  shown  in  Figure  4-3  and   the   format 
for  I-  and  D-space  tasks  is  shown  in  Figure  4-4, 


JSR        PC.Ca.NAUTO 

PC  RELATIVE  OFFSET  TO    NAUTO 

SEGMENT  DESCRIPTOR  ADDR. 

ENTRY  POINT  ADDRESS 

ZK.415-61 

Figure  4-3   Autoload  Vector  Format  for  Conventional  Tasks 


For  I-  and  D-space  tasks,  TKB  generates  the  autoload  vector  in  a 
format  that  differs  from  the  vector  in  a  conventional  task.  The  I- 
and  D-space  autoload  vector  is  six  words  long  and  consists  of  two 
parts:  one  part  residing  in  I-space  and  the  other  part  residing  in 
D-space.  The  I-space  part  consists  of  two  2-word  instructions,  and 
the  D-space  part  cons'sts  of  two  words  of  data.  The  data  in  the 
vector  are  the  segment  descriptor  address  and  the  target  entry  point 
address.   The  I-  and  D-space  vector  is  shown  in  Figure  4-4. 
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The  task  root  and  the  overlay  segments  may  contain  autoload  vectors; 
the  l-space  part  of  the  root  or  segment  contains  the  I-space  part  of 
the  vectors,  and  the  D-space  part  of  the  root  or  segment  contains  the 
D-space  part  of  the  vectors. 

The  MOV  instruction  in  the  I-space  part  of  the  vector  places  the 
address  of  the  D-space  part  of  the  vector  on  the  stack.  The  second 
instruction  in  the  vector  executes  an  indirect  JMP  to  $AUTO  through 
the  location  .NAUTO. 


MOV  (PC)..-(SP) 


ADDRESS  OF  PACKET  (D-SPACE) 


JMP  (a  NAUTO 


PC  RELATIVE  OFFSET  TO  NAUTO 


I-SPACE  PORTION 


ADDRESS  OF  SEGMENT  DESCRIPTOR 


ENTRY  POINT  ADDRESS 


D-SPACE  PORTION 


2K.  1089-8? 


Figure  4-4   Autoload  Vector  Format  for  I-  and  D-space  Tasks 

In  Figures  4-3  and  4-4,  a  transf er-of-control  instruction  to  the 
up-tree  global  symbol  generates  an  autoload  vector  in  the  shown 
format.  An  example  of  the  code  sequence  used  in  a  call  to  a  global 
symbol  in  an  autoloadable  segment  is  shown  in  Figure  4-5. 


USER  TASK  ROOT 


CALL  GLOBAL 


AUTOLOAD  VECTOR 

JSR  PC  (0  NAUTO 

SEGMENT  DESCRIPTOR  ADDRESS 

ENTRY  POINT  ADDRESS  (GLOBAL! 


USER  TASK  SEGMENT 
GLOBAL         •  •* 


i 


SAUTO  AUTOLOAD  ROUTINE 
$AUTO  •  LOAD 

•  ;SEGMENT 


JMP  GLOBAL    GO  TO 

.GLOBAL  IN 
.SEGMENT 


RETURN 


Figure  4-5   Example  Autoload  Code  Sequence  for  a  Conventional  Task 
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An  exception  to  the  procedure  for  generating  autoload  vectors  is  made 
in  the  case  of  a  program  section  with  the  data  (D)  attribute. 
References  from  a  segment  to  a  global  symbol  up-tree  in  a  program 
section  with  the  data  (D)  attribute  are  resolved  directly. 

Because  TKB  can  obtain  no  information  about  the  flow  of  control  within 
the  task,  it  often  generates  more  autoload  vectors  than  are  necessary. 
However,  your  knowledge  of  the  flow  of  control  within  your  task,  and 
of  path  loading,  can  help  you  determine  where  to  place  the  autoload 
indicators.  By  placing  the  autoload  indicators  only  at  the  points 
where  loading  is  actually  required,  you  can  minimize  the  number  of 
autoload  vectors  generated  for  the  task. 

In  the  following  example,  all  the  calls  to  overlays  originate  in  the 
root  segment.  That  is,  no  module  in  an  overlay  segment  calls  outside 
its  segment.   The  root  segment  CNTRL  has  the  following  contents: 

PROGRAM  CNTRL 
CALL  Al 
CALL  A21 
CALL  A2 
CALL  AO 
CALL  A22 
CALL  BO 
CALL  Bl 
CALL  B2 
CALL  CI 
CALL  C2 
CALL  C3 
CALL  C4 
CALL  C5 
END 

If  you  place  the  autoload  indicator  at  the  outermost  level  of 
parentheses,  13  autoload  veccors  are  generated  for  this  task; 
however,  because  A2  and  AO  are  loaded  by  path  loading  to  A21,  the 
autoload  vectors  for  A2  and  AO  are  unnecessary.  Moreover,  because  the 
call  to  CI  loads  the  segment  that  contains  C2 ,  C3,  C4 ,  and  C5 , 
autoload  vectors  for  C2  through  C!j  are  unnecessary. 

You  can  eliminate  the  unnecessary  autoload  vectors  by  placing  the 
autoload  indicator  only  at  the  points  where  explicit  loading  is 
required,  as  follows: 

CNTRL-  (AFCTR,*BFCTR,CFCTR) 
A0-(*A1,A2-*(A21,\22) ) 
(B0-(B1,B2) ) 
*C1-C2-C3-C4-C5 

With  this  DDL  description,  TKB  generates  seven  autoload  vectors  --  for 
Al,  A21f  A22,  BO,  PL,  82,  and  CI. 


AFCTR: 

.FCTR 

BFCTR: 

.FCTR 

CFCTR: 

.FCTR 

.END 
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4.1.4   Autoloadable  Data  Segments 

You  can  make  overlay  segments  that  contain  no  executable  code 
autoloadable,  as  follows.  First,  you  must  include  a  .NAME  directive 
and  specify  the  GBL  attribute,  as  described  in  Section  3.4.4.  For 
example: 

.ROOT  A-*(B,C) 

.NAME  BNAME,GBL 

B:      .FCTR  BNAME-BFIL 
.END 

The  global  symbol  BNAME  is  created  and  entered  into  the  symbol  table 
of  segment  BNAME.  Because  this  segment  is  marked  to  be  autoloaded, 
root  segment  A  calls  segment  BNAME  as  follows: 

CALL  BNAME 

The  segment  is  autoloaded  and  an  immediate  return  to  inline  code 
occurs . 

The  data  of  BFIL  must  be  placed  in  a  program  section  with  the  data  (D) 
attribute  to  suppress  the  creation  of  autoload  vectors. 


4.2   MANUAL  LOAD 

If  you  decide  to  use  the  manual-load  method  to  load  segments,  you  must 
include  in  your  program  explicit  calls  to  the  $LOAD  routine.  These 
load  requests  must  supply  the  name  of  the  segment  to  be  loaded.  In 
addition,  they  can  include  information  necessary  to  perform 
asynchronous  load  requests,  and  to   andle  load  request  failures. 

The  $LOAD  routine  does  not  path  loaa.  A  call  to  $LOAD  loads  only  the 
segment  named  in  the  request.  The  segment  is  read  in  from  disk  and 
mapped.  For  memory-resident  overlays;  the  segment  is  mapped,  but 
only  read  in  if  it  was  not  previously  read  in. 

A  MACRO-11  programmer  calls  the  $LOAD  routine  directly.  A  FORTRAN 
programmer  calls  $LOAD  using  the  FORTRAN  subroutine  MNLOAD. 


4.2.1   MACRO-11  Manual  Load  Calling  Sequence 

A  MACRO-11  programmer  calls  $LOAD  as  follows: 

MOV      #PBLK.RO 
CALL     $LOAD 

PBLK  is  the  address  of  a  parameter  block  with  the  following  format; 

PBLK:      .BYTE  length , event-flag 
.RAD50  /seg-name/ 
.WORD  [i/o-status]  or  0 
.WORD  [ast-trp]  or  0 

length 

The  length  of  the  parameter  block  (3  to  5  words) . 
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event-flag 


The  event  flag  number,  used  for   asynchronous   loading.    If   the 
event-flag  number  is  0,  synchronous  loading  is  performed. 


seg-name 


The  name  of  the  segment   to   be   loaded:    a   1-   to   6-character 
Radix-50  name,  occupying  two  words. 


i/o-status 


The  address  of  the  I/O  status  doubleword .    Standard   QIO   status 
codes  apply. 

ast-trp 

The  address  or  an  asynchronous   trap   service   routine   to   which 
control  is  transferred  at  the  completion  of  the  load  request. 

The  condition  code   C-list   is   set   or   cleared   on   return,   as 
follows : 

•  If  condition  :ode  C=0,  th   load  request  was  accepted. 

•  If  condition  code  C=l,  the  load  request  was  unsuccessful. 

For  a  synchronous  load  request,  the  return  of  the  condition  code  C=0 
means  that  the  desired  segment  is  loaded  and  is  ready  to  be  executed. 
For  an  asynchronous  load  request,  the  return  of  the  code  C»0  means 
that  the  loa<.  request  was  successfully  queued  to  the  device  driver, 
but  the  segment  is  not  necessarily  in  memory.  Your  program  must 
ensure  th.^'-  loading  has  been  completed  by  waiting  for  the  specified 
event  flag  oefore  calling  any  routines  or  accessing  any  data  in  the 
segment . 


4.2.2  NACRO-11  Hanual  Load  Calling  Sequence  For  I-  and  D-Space  Tasks 

A  MACRO-11  programmer  calls  $LOAD  as  follows: 

MOV    #PBLK,RO 
CALL   $LOAD 

PBLK  is  the  address  of  a  parameter  block  with  the  following  format   in 
an  I-  and  D-space  task: 

PBLK:  BYTE  3,0 

.RAD50  /seg-name/ 

length 

The  length  of  the  parameter  block  (3  words) . 


w 
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event-flag 


•A'  1  ■.  V"  '.^Ay- 


Specify  this  as  0.   Only  synchronous  load  requests   are   possible 
when  loading  I-  and  D- space  segments. 


seg-name 

The  name  of  the  segment   to   be   loaded:    a   1-   to   6-character 
Radix-50  name,  occupying  two  words. 

The  condition  code  C-list  is  set  or  cleared  on  return,  as  follows: 

•  If  condition  code  C<«0,  the  load  request  was  accepted. 

•  If  condition  code  C»l,  the  load  request  was  unsuccessful. 

For  a  synchronous  load  request,  which  is  the  only  one  possible  for  I- 
and  D-space  segmenls,  the  return  of  the  condition  code  C=0  means  that 
the  desired  segment  is  loaded  and  is  ready  to  be  executed.  Your 
program  must  ensure  that  loading  has  been  successful  by  checking  for 
the  condition  code  rather  than  assuming  that  the  segment  has  been 
loaded. 


4.2.3   FORTRAN  Manual  Load  Calling  Sequence 

To  use  the  manual  load  mechanism  in  a  FORTRAN  program,  your  program 
must  refer  to  the  $LOAO  routine  by  means  of  the  MNLOAD  subroutine. 
The  subroutine  call  has  the  form: 

CALL  MNLOAD (seg-name, [event-flag]  ,[i/o- status]  ,(ast-trp]  ,[ld-ind]) 

seg-name 

A  2-word  real  variable  containing  the  segment  name  in  Radix-50 
format . 

event-flag 

An  optional  integer  event  flag  number  used  for  an  asynchronous 
load  request.  If  the  event  flag  number  is  0,  the  load  request  is 
synchronous . 

i/o-status 

An  optional  2-word  integer  array  containing  the  I/O  status 
doubleword,  as  described  for  the  QIO  directive  in  the 
RSX-llM/M-PLUS  Executive  Reference  Manual. 

ast-trp 

An  optional  asynchronous  trap  subroutine  entered  at  the 
completion  of  a  request.  MNLOAD  requires  that  all  pending  traps 
specify  the  same  subroutine. 
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Id-ind 


An  optional   integer   variable   containing   the   results   of   the 
subroutine  call.   One  of  the  following  values  is  returned: 

+1   Request  was  successfully  executed. 

-1   Request   had   bad   parameters   or   was   not    successfully 
executed. 

You  can  omit  optional  arguments.   The  following  calls  are  legal: 


Call 


CALL  MNLOAD  (SEGAl) 


CALL  MNLOAD  ( SEGAl , 0 ,,, LDIND) 


CALL  MNLOAD  { SEGAl , 1 , lOSTAT , ASTSUB , LDIND) 


Effect 

Loads  segment  named  in 
SEGAl  synchronously. 

Loads  segment  named  in 
SEGAl  synchronously  and 
returns  success  indica- 
tor to  LDIND. 


Loads  segment  named  in 
SEGAl  asynchronously, 
transferring  control  to 
ASTSUB  upon  completion 
of  the  load  request; 
stores  the  I/O  status 
doubleword  in  lOSTAT 
and  the  success 
indicator  in  LDIND. 


in 


The  following  example  uses  the  program  CNTRL,  previously  discussed 
section  4.1.  In  tnis  example,  there  is  sufficient  processing  between 
the  calls  to  the  overlay  segments  to  make  asynchronous  loading 
effective.  The  autoload  indicators  are  removed  from  the  ODL 
description  and  the  FORTRAN  programs  are  recompiled  with  explicit 
calls  to  the  MNLOAD  subroutine,  as  follows: 


PROGRAM  CNTRL 
EXTERNAL  ASTSUB 
DATA  SEGAl  /6RA1 
DATA  SEGA21  /6RA21 


/ 
/ 


CALL  MNLOAD  ( SEGAl , 1 , lOSTAT , ASTSUB, LDIND) 


CALL 


CALL  Al 


MNLOAD  (SEGA21,1, lOSTAT, ASTSUB, LDIND) 


4-10 


OVERLAY    r.OADING    METHODS 


CALL  A21 


END 

SUBROUTINE  ASTSUB 

DIMENSION  I0STAT(2) 


END 

When  the  AST  trap  routine  is  used,  the  I/O  status  doubleword  is 
automatically  supj      to  the  dummy  variable  lOSTAT. 

! 
4.2.4   FORTRAN  Manual  Load  Calling  Sequence  £or  I-  and  D-Space  Tasks 

To  use  the  manual  load  mechanism  in  a  FORTRAN  program,  your  program 
must  refer  to  the  $LOAD  routine  by  means  of  the  MNLOAD  subroutine. 
The  subroutine  call  has  the  form: 

CALL  MNLOAD (seg-name, , , , [Id-ind] ) 

seg-name 

A   2-word    real    variable  containing    the   segment      name      in      Radix-50 
format. 

l<ii<-ind 

An  optional   integer   variable  containing   the   results   of   the 
subroutine  call.   One  of  the  following  values  is  returned: 

*1      Request  was  successfully  executed. 

-1   Request  had  bad  parameters  or  was  not  successfully 
executed. 

You  can  omit  optional  arguments.   The  following  calls  are  legal: 

Call  Effect 

CALL  MNLOAD  (SEGBl)  Loads  segment   named    in   SEGBl 

synchronously. 

CALL  MNLOAD  (SEGBl ,,, ,LDIND)      Loads   segment   named   in   SEGBl 

synchronously  and  returns  success 
indicator  to  LDIND. 

Only  synchronous  loading  is  possible  when  manually  loading  I-  and 
D-space  task  segments. 


4.3   ERROR  HANDLING 

If  you  use  the  autoload  mechanism,   a  simple   recovery   procedure   is 

provided   that   checks   the   Directive  Status  Word  (DSW)  for  an  error 

indication.   If  the  DSW  indicates  that  no  system   dynamic   storage   is 

available,   the   routine  issues  a  Wait  for  Significant  Event  directive 
and  tries  again;   if  the  problem  is  not  dynamic  storage,  the   recovery 
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procedure   generates   a   synchronous   breakpoint   trap, 
cervices  the  trap  and   returns   without   altering   the 
program,  the  request  will  be  retried. 


If   the  task 
state   of   the 


Tf  you  select  the  manual-load  method,  you  must  provide  error  handling 
routines  that  diagnose  load  errors  and  provide  appropriate  recovery. 
A  more  comprehensive  user-written  error  recovery  subroutine  can  be 
substituted  for  the  system-provided  routine  if  the  following 
conventions  are  observed: 


«   The  error  recovery  routine  must 
SALERR. 


have   the   entry   point   name 


•   The  contents  of  all  registers  must  be  saved  and  restored. 

On  entry  to  $ALERR,  R2  contains  the  address  of  the  segmer.t  descriptor 
that  could  not  be  loaded.  Before  recovery  action  can  be  taken,  the 
routine  must  determine  the  cause  of  the  error  by  examining  the 
following  words  in  the  sequence  indicated: 

1.  $DSW       The  Directive  Status  Word   may   contain   an   error 

status  code,  indicating  that  the  Executive 
rejected  the  I/O  request  to  load  the  overlay 
segment . 

2.  N.OVPT     The  contents  of  this  location,  offset   by   N.IOST, 

point  to  a  2-word  I/O  status  block  containing  the 
results  of  the  load  overlay  request  returned  by 
the  device  driver.  The  status  code  occupies  the 
low-order  byte  of  word  0.  For  example,  for  a 
device-not-ready  condition,  the  code  will  be 
lE.DNR.  (For  more  information  on  these  codes, 
refer  to  the  IAS/RSX-11  I/O  Operations  Reference 
Manual . ) 


4.4   GLOBAL  CROSS-REFERENCE  OF  AN  OVERLAID  TASK 

This  section  illustrates  a  global  cross-reference  that  has  been 
created  for  an  overlaid  task.  The  task  consists  of  a  root  segment 
containing  the  module  ROOT. OBJ,  and  overlay  segments  composed  of 
modules  OVRl,  0VR2,  0VR3 ,  and  0VR4 .  The  overlay  description  of  the 
file  is  as  follows: 


.ROOT 
OVR:  .FCTR 


ROOT- (0VR,*0VR2) 
0VR1-* (OVR3,OVR4) 


Only  segments  0VR2 ,  0VR3 ,  and  0VB4  are  autoloadable , 
the  resulting  overlay  tree. 


Figure  4-6  shows 


•0VR3 


OVRl 


•0VR4 


I 

ROOT 


ROOT 


•OVR? 


CALL  0VR3 
CALL  OVRl 
CALL  0VR2 


Figure  4-6   Autoload  Overlay  Tree  Example 


4-12 


OVERLAY  LOADING  METHODS 


As  shown,  the  global  symbol  OVRl  is  defined   in   module  OVRl,   and   a 

simjle   nonautoloadable ,   up-tree   reference  is  made  to  this  symbol  by 

the  module  ROOT,  as  indicated  by  the  circumflex.    Note  that   because 

OVRl   is  not  autoloadable ,  it  depends  on  a  call  to  0VR3  or  0VR4  to  get 
loaded  by  path   loading.    The   asterisk   indicates   that   the   module 

contains   an   autoloadable   definition.    The   modules  shown  with  the 
asterisk  define  tlie  symbol. 


The  asterisk  and  at-sign  are  shown  in  the  cross-reference   listing   in 
Example  4-1. 


Example  4-1   Cross-Ref erence  Listing  of  Overlaid  Task 


OVRTST      CREATED  BY    TKB 
GLOBAL  CROSS  REFERF  JE 


ON  27-JUL-82  AT  12:04 


PAGE  1 
CREf     vol 


SYMBOL 

VALUE 

1 

REFERENCES 

N.ALER 

000010 

AUTO 

# 

OVRES 

N. lOST 

000004 

OVCTL 

« 

OVRES 

N.MRKS 

000016 

# 

OVRES 

N.OVLY 

000000 

OVCTL 

# 

OVRES 

N.OVPT 

000054 

AUTO 

OVCTL 

#  VCTDF 

N. RDSG 

000014 

# 

OVRES 

N.STBL 

000002 

# 

OVRES 

N.SZSG 

000012 

# 

OVRES 

OVRl 

002014-R 

# 

OVRl 

* 

ROOT 

0VR2 

002014-R 

* 

0VR2 

§ 

ROOT 

0VR3 

002014-R 

* 

0VR3 

0 

ROOT 

0VR4 

002014-R 

* 

0VR4 

@ 

ROOT 

ROOT 

001176-R 

# 

ROOT 

$ALBP1 

001320-R 

# 

AUTO 

$ALBP2 

001416-R 

« 

AUTO 

SALERR 

001246-R 

# 

ALERR 

OVDAT 

$AUT0 

001302-R 

« 

AUTO 

$DSW 

000046 

ALERR 

« 

VCTDF 

$MARKS 

001546- R 

# 

OVCTL 

$OTSV 

000052 

» 

VCTDF 

$SAVRG 

001452-R 

AUTO 

# 

SAVRG 

$VEXT 

000C56 

« 

VCTDF 

. FSRPT 

000050 

« 

VCTDF 

.NALER 

001442-R 

# 

OVDAT 

.NIOST 

001436-R 

# 

OVDAT 

•NMRKS 

001450-R 

# 

OVDAT 

. NOVLY 

001432-R 

# 

OVDAT 

.NOVDT 

000042 

# 

OVDAT 

.NRDSG 

001446-R 

# 

OVDAT 

.NSTBL 

001434-R 

# 

OVDAT 

.NSZSG 

001444-R 

» 

OVDAT 
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Example  4-1  (Cont.)   C,.os3-Ref erence  Listing  of  Overlaid  Task 


OVRTST      CREATED  BY    TKB      ON  27-JUL-82  AT  12:04 

SEGMENT  CROSS  REFERENCE 

SEGMENT  NAME     RESIDENT  MODULES 


OVRl 
0VR2 
0VR3 
0VR4 
ROOT 


PAGE  2 
CREF     vol 


OVRl 

0VR2 

0VR3 

0VR4 

ALERR    AUTO    OVCTL    CVDAT    OVRES    ROOT    Skv/RG 

VCTDF 


Down-tree  references  to  the  global  symbol  ROOT  are  made   from   modules 
OVRl,  0VR2,  0VR3,  and  0VR4 .   These  references  are  resolved  directly. 

The  segment  cross-reference  shows  the  segment  name  and  modules  in  each 
overlay. 


4.5   USE  AND  SIZE  OF  OVERLAY  RUNTIME  ROUTINES 

TKB,  when  constructing  an  overlaid  task,  incorporates  certain  modules 
from  the  system  library  to  perform  the  actual  overlay  operations.  An 
overlay  run-time  routine  in  the  task  loads  overlays  from  disk  or  maps 
resident  overlays  by  issuing  QIO$  or  CRAW$  directives. 


The  modules  and  routines  described  below  implement   the  TKB 
mechanism  as  described  in  Section  4.1. 


autoload 


There  are  three  major  components  to  the  autoload  service,  as  follows: 

AUTO  This  module  controls  the  overlay  process,  and  the 
autoload  vecors  indirectly  call  AUTO  through  .NAUTO. 
AUTO  determines  whether  the  referenced  overlay  segment 
is  already  in  memory  or  mapped.  It  then  jumps  to  the 
required  entry  point  if  the  entry  point  is  available. 

The  AUTO  module  is  supplied  in  two  variations.  These 
variations  are  separately  named  and  described  as 
follows : 

AUTO  Selected  by  TKB  by  default  for  all  overlaid 
tasks.  It  manages  disk-only,  PLAS,  and  cluster 
library  overlay  structures. 

AUTOT  Manually  selected  by  you  by  using  an  explicit 
reference  in  the  TKB  .ODL  file,  as  shown  below. 
This  module  disables  the  AST  traps  while 
manipulating  the  overlay  data  structures.  This 
is  required  where  user  task  AST  traps  might 
cause  modification  of  the  overlay  database.  To 
incorporate  this  module  in  your  task  image,   you 


• 
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must  include  the  following  element  in  the   .ROOT 
factor  of  the  task's  ODL  file: 


-LB: [1 ,1]SYSLIB/LB:AUT0T- 

In  addition  to  including  AUTOT  in  the  .ROOT 
factor,  the  following  code  must  be  included  in 
your  task  as  initialization  prior  to  the  AST 
handling  routines  in  your  task: 

MOV  §#.NOVPT,R0 
BISB  #200,N.FAST(R0) 

MRKS  This  routine  traverses  the  overlay  descriptor  data 
structure  to  mark  any  overlay  segment  that  will  be 
displaced  by  a  new  overlay  as  "out  of  memory"  and 
consequently  not  available. 

RDSG  The  AUTO  module  calls  the  RDSG  routine  repeatedly  to 
read  or  map  each  segment  along  the  overlay  tree  path 
into  the  task's  virtual  address  space.  This  is  referred 
to  as  "path  loadirig."  When  path  loading  is  completed, 
AUTO  calls  the  required  entry  point. 

Sever3l  versions  of  each  component  exist  reflecting  the  various  sizes 
as  appropriate  for  tasks  having  disk-only  overlays,  PLAS  mapped 
overlays,  and/or  cluster  libraries.  TKB  incorporates  the  smallest 
support  routines  appropriate  for  the  overlay  structure  of  your  task. 

Depending  on  whether  your  task  has  disk-only  overlays,  resident 
overlays,  or  cluster  libraries,  TKB  forces  one  of  the  following 
modules  into  your  task: 

OVCTL     Contain  the   MRKS   and   RDSG  routines  optimized  for  disk 

C'lDL     overlays   only.     No    support    is     included     for 

memory-resident   or   cluster   overlays.    OVCTL   is   the 

module  included  for  conventional  tasks,  and  OVIDL  is  the 

module  included  for  I-  and  D-space  tasks. 

OVCTR  Contain  MRKS  and  RDSG  routines  assembled  for  disk  and 
OVIDR  memory  resident  overlays.  TKB  selects  either  of  these 
modules  if  the  task  overlay  structure  includes 
memory-resident  overlays  or  maps  a  resident  library 
containing  resident  overlays.  OVCTR  is  the  module 
selected  for  conventional  tasks  and  non-overlaid  I-  and 
D-space  tasks.  OVIDR  is  the  module  selected  for 
overlaid  I-  and  D-space  tasks. 

OVCTC  Contain  the  MRKS,  RDSG,  and  cluster  library  support 
OVIDC  routines.  TKB  includes  OVCTC  or  OVIDC  if  cluster 
libraries  are  included  in  your  task.  OVCTC  is  the 
module  selected  for  conventional  tasks  and  non-overlaid 
I-  and  D-space  tasks.  OVIDC  is  the  module  selected  for 
overlaid  I-  and  D-space  tasks. 
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Two  other  modules  are  incorporated  into  your  task's  image.   They  are: 

OVDAT  A  small,  impure  data  area  used  by  AUTO,  MRKS,  and  RDSG 
routines.  TKB  includes  OVDAT  in  all  overlaid  tasks,  md 
its  size  is  independent  of  the  overlay  structure  of  that 
task . 

ALERR  An  error  service  module  that  AUTO  invokes  under  one  of 
the  following  circumstances: 

•  If  an  I/O  error  occurs  while  attempting  to  read  a 
disk  overlay  into  memory 

•  If  a  directive  error  occurs  while  attempting  to 
attach  or  map  a  region  containing  memory  resident 
overlays 

Table  4-1  compares  the  sizes  of  the  overlay  run-time  support  modules. 
You  can  use  it  to  determine  when  it  is  appropriate  to  rorce  certain 
variants  into  your  task  image. 

Table  4-1 
Comparison  of  Overlay  Run-Time  Module  Sizes 


Module 


Number 
Program   of  Bytes 
Section    Oct/Dec 


Specific  Use 


One  of  the  following  modules  is  included  in  any  overlaid  task 
that  uses  autoload  and  in  any  task  that  links  to  a  PLAS  overlaid 
resident  library. 


AUTO 
AUTOT 


$$AUTO    122/82, 


$$AUTO 

$$RTQ 

$$RTR 


132/90. 
32/26. 
30/24. 


All  tasks  that  use  autoload 

All  tasks  with  ASTs 
disabled  during  autoload 


One  of  the  following  modules  is  included  in  any  overlaid 
conventional  task.  OVCTR  or  OVCTC  is  included  in  any 
non-overlaid  task  (conventional  or  1-  and  D-  space)  that  links 
to  a  PLAS  overlaid  resident  library. 


OVCTL      $$MRKS     76/62. 
$$RDSG    160/112. 
$$PDLS      2/2. 


Disk  overlays  only 


OVCTR 


OVCTC 


$$MRKS 
$$RDSG 
$$PDLS 

$$MRKS 
$$RDSG 
$$PDLS 


234/156, 

332/218, 

12/10. 

254/172, 
352/234, 
120/80. 


Disk  and  PLAS  overlays  with  no 
cluster  libraries 


Disk  and  PLAS  overlays 
with  cluster  libraries 


(continued  on  next  page) 
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Table  4-1  (Cont.) 
Comparison  of  Overlay  Run-Time  Module  Sizes 


Number 
Program   of  Bytes 
Module    Section    Oct/Dec 


Specific  Use 


One  of  the  following  three  modules  is  included  in  any  overlaid 
I-  and  D-space  task. 


OVIDL      $$MRKS     76/62. 
$$RDSG    224/148. 


$$PDLS 


2/2, 


Disk  overlays  only 


OVIDR      $$MRKS    304/196. 
$$RDSG    502/322. 


$$PDLS 


12/10. 


Disk  and  PLAS  overlays 
with  no  cluster  libraries 


OVIDC  $$MRKS  324/212. 
$$RDSG  522/338. 
$$PDLS    120/80. 


Disk  and  PLAS  overlays 
with  cluster  libraries 


The  overlay  data  vector  OVDAT  is  included  in  any   overlaid   task 
and  in  any  task  that  links  to  a  PLAS  overlaid  resident  library. 


OVDAT 


$$OVDT 

24/20 

$$SGDO 

0/0. 

$$SGD2 

2/2. 

$$RTQ 

0/0. 

S$RTR 

0/0. 

S$RTS 

2/2. 

Included  in  all  tasks 
that  perform  overlay 
operat  ions 


The  overlay  error  service  routine   ALERR   is   included   whenever 
OVDAT  is  included. 


ALERR 


$$ALER 


24/20, 


Overlay  error 


Manual  overlay  control  (LOAD)  is   used   in   place   of   any   AUTO 
routine.   (See  Section  4.2,  Manual  Load.) 


LOAD 


$$LOAD 
$$AUTO 


252/170, 
14/12. 


Manual  ov'erlay  control 
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CHAPTER  5 
SHARED  REGION  CONCEPTS  AND  EXAMPLES 


The  Task  Builder  provides  you  with  many  ways  of  using  shared  regions 
for  tailoring  your  tasks  to  meet  your  specific  requirements.  This 
chapter  describes  some  of  these  facilities  and  their  applications. 

This  chapter  contains  five  working  examples.  The  discussion  of  the 
examples  assumes  that  you  are  familiar  with  the  programming  concepts 
described  in  the  RSX-llM/M-PLUS  Guide  to  Program  Development  and  with 
the  first  four  chapters  of  this  manual. 


5.1   SHARED  REGIONS  DEFINED 

A  shared  region  is  a  block  of  data  or  code  that  resides  in  memory  and 
can  be  used  by  any  number  of  tasks.  A  shared  region  can  contain  data 
for  use  by  several  tasks  or  it  may  be  an  area  where  one  task  writes 
data  for  use  by  another  task.  Also,  a  shared  region  can  contain 
routines  for  use  by  several  tasks. 

Shared  regions  are  useful  because  they  make  more  efficient  use  of 
physical  memory.   The  two  kinds  of  shared  regions  are: 

•  A  resident  common  that  provides  a  way  that  two  or   more   tasks 
can  share  their  data 

•  A  resident  library  that  provides  a  way  that  two  or  more   tasks 
can  share  a  single  copy  cf  commonly  used  subroutines 

The  term  "resident"  denotes  a  shared  region  that  is  built  and 
installed  into  the  system  separately  from  the  task  that  links  to  it. 
In  other  words,  you  use  TKB  to  build  a  shared  region  much  as  you  would 
use  it  to  build  a  task.  However,  the  region  does  not  have  a  header  or 
a  stack.  Also,  you  can  use  switches  to  designate  the  kind  of  shared 
region  (a  library  or  a  common)  to  be  built. 

Figure  5-1  shows  a  typical  resident  common.  Task  A  stores  some 
results  in  resident  common  S,  and  Task  B  retrieves  the  data  from  the 
common  at  a  later  time. 

Figure  5-2  shows  a  typical  resident  library.  In  this  case,  common 
reentrant  subroutines  are  no*  included  in  each  task  image;  instead,  a 
single  copy  is  shared  by  all  tasks. 
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PARTITION  BOUNDARY 


PARTITION  BOUNDARY 


RESIDENT  COMMON 
S 

TASK  A 

EXECUTIVE 

1 

RESIDENT  COMMON 
S 


TASK  B 


EXECUTIVE 


PHYSICAL  MEMORY 
TIME  1 


PHYSICAL  MEMORY 
TIME  2 


Figure  b-1   Typical  Resident  Common 
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In  an  RSX-llM  system,  a  shared  region  must  reside  in  its  own 
partition.  Therefore,  when  you  generate  your  system,  you  must 
consider  the  physical  memory  requirements,  in  terms  of  partitions,  for 
any  shared  regions  that  you  expect  to  reside  within  yout  system.  If 
you  do  not  consider  these  requirements  at  system  generation  time, 
later,  when  you  build  a  shared  region,  you  will  be  forced  uo  go  back 
and  create  a  common  partition  for  the  region. 
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PARTITION  BOUNDARY 
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Figure  5-2   Typical  Resident  Library 


In  an  RSX-llM-PLUS  system,  shared  regions  do  not  have  to  reside 
partitions   of   their   own;    you   can   install  a  shared  region 
partition  large  enough  to  hold  it.   In  fact,  the  partition   for 
the   shared   region   was  built  does  not  have  to  exist  in  the  sys 
the  time  the  shared  region  is  installed.   Then,  it  follows  that 
command   sequence  or  build  file  for  a  memory-resident  overlaid  1 
must  contain  the  statement  PAR^xxx,  where  xxx  is  the  same  name  a 
of   the   region   being   built.    Then,  when  you  attempt  to  insta 
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5.1.1   The  Symbol  Definition  File 

When  you  build  a  shared  region,  you  must  specify  a  symbol  definition 
(.STB)  file  in  the  TKB  command  sequence.  This  file  contains  linkage 
information  about  the  region.  (The  format  at  a  .STB  file  as  input  to 
TKB  is  the  same  as  that  of  a  .OBJ  file.  See  Appendix  A.)  Later,  when 
you  build  a  task  that  links  to  the  region,  TKB  uses  this  .STB  file  to 
resolve  calls  from  within  the  referencing  task  to  locations  within  the 
region . 
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If  you  dc  not  use  either  /CO  or  /LI,  the  contents  of  an  .STB  file  for 
a  sharefi  region  depend  on  the  use  of  the  /PI  switch,  which  determines 
whether  the  region  is  absolute  or  relocatable.  The  effects  of 
declaring  a  shared  region  relocatable  or  absolute  and  the  resulting 
contents  of  the  .STB  file  are  described  in  the  following  sections. 

Some  .STB  files  include  an  entry  in  the  .STB  file  for  each  program 
section  in  the  region.  Each  entry  declares  the  program  section's 
name,  attributes,  and  length.  In  addition,  TKB  includes  in  the  .STB 
file  every  symbol  in  the  shared  region  and  its  value  relative  to  the 
beginning  of  the  section  in  which  it  resides. 


5.1.2   Position-Independent  Shared  Regions 

A  position-independent  shared  region  can  be  placed  anywhere  in  a 
referencing  task's  virtual  address  space  when  the  system  on  which  the 
task  runs  has  memory  management  hardware. 


5.1.2.1  Position-Independent  Shared  Region  Mapping  -  In  the  example 
of  using  the  memory  management  APRs,  shown  in  Figure  5-4,  two  tasks 
refer  to  the  shared  region  S:  task  A  and  task  B.  The  shared  region  S 
is  4K  words  long  and  therefore  requires  that  much  space  in  the  virtual 
address  space  of  both  tasks.  Task  A  is  6K  words  long  and  requires  two 
APRS  (APRO  and  APRl)  to  map  its  task  region.  The  first  APR  available 
to  map  the  shared  region  is  APR  2.  Thus,  you  can  specify  APR  2  wisen 
task  A  is  built. 

Task  B  is  16. 5K  words  long.  It  requires  five  APRs  to  map  its;  task 
region.  The  first  APP  available  to  map  the  shared  region  S  in  task  B 
is  APR  5.   Therefore,  you  can  specify  APR  5  when  task  B  is  built. 

If  you  do  not  specify  ./hich  APR  is  to  be  used  to  map  a 
position-independent  shared  region,  TKB  selects  the  highest  set  of 
APRS  available  in  the  referencing  task's  virtual  address  space.  In 
Figure  5-4,  for  example,  if  APR  2  in  task  A  and  APR  5  in  task  B  had 
not  been  selected  at  task-build  time,  TKB  would  have  selected  APR  7  in 
both  cases. 


5.1.2.2  Specifying  a  Position-Independent  Region  -  You  specify  that  a 
shared  region  is  position  independent  when  you  build  it  by  attaching 
the  /PI  switch  to  the  image  file  specification  for  the  region.  (Refer 
to  Chapter  10  for  a  description  of  the  /PI  switch.) 

You  should  declare  a  region  position  independent  if: 

•  The  region  contains  code  that  will  execute  correctly 
regardless  of  its  location  in  the  address  space  of  the 
referencing  task. 

•  The  region  contains  data  that  is  not  address  dependent. 

•  The  region  contains  data  that  will  be  referenced  by  a  FORTRAN 
program  (such  data  must  reside  in  a  named  common) . 
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Figure    5-4      Specifying    APRs    for    a    Position-Independent    Shared    Region 
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Program  section  names  are  preserved  in  some  shared  regions.  All  the 
following  switch  combinations  produce  shared  regions  in  which  PSECT 
names  are  preserved: 

/PI/CO,  /-PI/CO,  and  /PI 

Therefore,  you  should  observe  the  following  precautions  when  building 
and  referring  to  these  regions: 

•  No  code  or  data  in  the  region  should  be  included  in  the  blank 
(.  BLK.)  program  section. 

•  No  code  or  data  in  a  referencing  task  should  appear  in  a 
program  section  of  the  same  name  as  a  program  section  in  the 
shared  region. 

•  The  order  in  which  memory  is  allocated  to  program  sections 
(alphabetic  or  sequential)  must  be  the  same  for  the  shared 
region  and  its  referencing  tasks.  (Chapter  2  describes 
alphabetic  ordering  of  program  sections.  Refer  to  the 
description  of  the  /SQ  and  /SG  switches  in  Chapter  10  for  an 
explanation  of  sequential  ordering  of  program  sections.) 


5.1.3   Absolute  Shared  Regions 

When  a  shared  region  is  absolute,  you  select  the  virtual  addresses  for 
it  when  you  build  it.  Thus,  an  absolute  shared  region  is  fixed  in  the 
virtual  address  space  of  all  tasks  that  refer  to  it. 


5.1.3.1  Absolute  Shared  Region  Mapping  -  Figure  5-5  shows  three  tasks 
(task  C,  task  D,  and  task  E)  and  a  single  absolute  shared  region,  L. 
The  absolute  shared  region  L  is  6K  words  long  and  is  built  to  occupy 
virtual  addresses  120000  (octal )  to  150000 (octal )  .  These  addresses 
correspond  to  APR  5  and  APR  6,  respectively.  Tasks  C  and  D  can  be 
linked  to  region  L  because  at  the  time  they  are  built  APR  5  and  APR  6 
are  unused  in  both  tasks.  However,  task  E  is  23K  words  long  and  even 
though  it  has  8K  words  of  virtual  address  space  available  to  map  the 
shared  region,  APR  5  (which  corresponds  to  virtual  address  120000,  the 
base  address  of  the  shared  region)  has  been  allocated  to  the  task 
region.  If  shared  region  L  were  position  independent,  task  E  could  be 
linked  to  it. 


5.1.3.2  Specifying  an  Absolute  Shared  Region  -  You  specify  that  a 
shared  region  is  absolute  when  you  build  it  by  using  the  /-PI  switch 
or  omitting  the  /PI  switch  from  the  task  image  file.  You  establish 
the  virtual  address  for  the  region  by  specifying  the  base  address  of 
the  region  as  a  parameter  of  the  PAR  option. 

You  should  build  an  absolute  shared  region  if: 

•  The  region  contains   code   that   must   appear   in   a   specific 
location  in  the  address  space  of  a  referencing  task. 

•  The  region  contains  data  that  is  address  dependent. 

•  The  region  contains  program   sections   of   the   same   name   as 
program  sections  in  referencing  tasks. 
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Figure    5-5      Mapping    for    an    Absolute    Shared    Region 
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5.1.3.3  Absolute  Shared  Region  .STB  File  -  When  a  shared  region  is 
created  with  the  /-PI/LI  or  /-PI  switches,  or  just  the  /-HD  switch, 
the  only  program  section  name  that  appears  in  the  .STB  file  for  the 
region  is  the  absolute  program  section  name  (.  ABS.).  TKB  includes  in 
the  .STB  file  for  the  region  each  symbol  in  the  region  and  its  value. 
But,  because  TKB  does  not  include  the  program  section  names  of  an 
absolute  shared  region  in  its  .STB  file,  all  code  or  data  in  the 
region  rrust  be  referred  to  by  global  symbol  name.  Also,  because  the 
program  section  names  are  not  in  the  .STB  file,  TKB  places  no 
restrictions  on  the  way  the  program  sections  are  ordered  in  either  the 
absolute  shared  region  or  the  tasks  that  reference  it.  You  can  order 
program  sections  the  way  you  want  by  using  the  /SQ  and  /SG  switches 
described  in  Chapter  10. 


5.1.4   Shared  Regions  with  Memory-Resident  Overlays 

Shared  regions  with  memory-resident  overlays  are  a  primary  resource 
for  conserving  memory.  If  the  shared  region  is  larger  than  the 
available  virtual  address  space  in  a  task  thut  must  reference  the 
region,  you  can  build  the  region  --  both  posi t ion- independent  and 
absolute  --  with  memory-resident  overlays.  All  segments  of  the 
overlay  structure  are  included  in  the  shared  region,  but  each  task 
referencing  the  shared  region  can  include  only  part  of  the  shared 
region  --  that  is,  an  overlay  segment  or  series  of  segments  in  an 
overlay  path  --  in  its  virtual  address  space.  Therefore,  the  task 
need  only  have  enough  virtual  address  space  for  the  largest  shared 
region  overlay  segment,  or  series  of  segments  in  an  overlay  path,  it 
is  likely  to  access.  Hence,  the  virtual  address  space  of  the  task  can 
be  considerably  smaller  than  the  size  of  the  shared  region. 


5.1.4.1  Considerations  About  Building  an  Overlaid  Shared  Region  -  In 
general,  overlays  can  be  disk-resident  or  memory-resident,  but  those 
in  shared  regions  must,  by  their  very  nature,  be  memory-resident.  TKB 
marks  each  overlay  segment  in  the  shared  region  with  the  NODSK 
attribute  to  suppress  overlay  load  requests.  When  you  build  a  shared 
region  with  memory-resident  overlays,  you  must  define  the  overlay 
structure  through  a  conventional  DDL  file.  (See  Chapters  3  and  4  of 
this  manual  for  information  on  overlays  and  the  Overlay  Description 
Language.)  TKB  does  not  include  the  overlay  data  base  (segment 
descriptors,  autoload  vectors,  and  so  forth)  or  the  overlay  run-time 
routines  within  the  region  image.  Instead,  this  data  base  becomes  a 
part  of  the  .STB  file  that  is  linked  to  the  referencing  task.  When 
this  task  is  built,  its  root  segment  automatically  includes  both  the 
data  base  and  global  references  to  overlay  support  routines  residing 
in  the  system  object  module  library. 

The  procedure  for  creating  a  shared  region  with  memory-resident 
overlays  can  be  summarized  as  follows: 

•   Define  an  overlay  structure   containing   only   memory-resident 
overlays . 
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5.1.4.2   Example  of  Building  a  Memory-Resident  Overlaid  Shared   Region 

-  Th«  procedure  for  creating  a  shared  region  is  illustrated  in  the 
following  example.  The  shared  region  to  be  contructed  consists  of 
reentrant  code  that  resides  within  the  overlay  structure  defined 
below: 

.ROOT  A- ! (B,C-D) 

.NAME  A 

.END 

Root  segment  A  contains  no  code  or  data  and  has  a  length  of  0.  All 
executable  code  exists  within  memory-resident  overlay  segments 
composed  of  object  modules  B.OBJ,  C.ODJ,  and  D.OBJ,  containing  global 
entry  points  B,  C,  and  D,  respectively. 

You  generate  the  .TSK,  .MAP,  and  .STB  files  by  using  the  following  TKB 
commands : 

TKB>A/-HD/MM,LP: ,SY:A=A/MP 

Enter  Options: 

TKB>GBLRKF=B,C,D 

TKB>PAR=A: 160000:20000 

TKB>STACK=0 

TKB>/ 


NOTE 

When  b'  ilding  a  shared  region,  you  must 
use  the  same  name  for  the  partition  and 
the  .TSK  and  .STB  files. 

See  the  PAR,  RESLIB,  LIB?,  RESCOM,  and 
COMMON  options  in  Chapter  11. 

TKB  inserts  references  to  entry  points  B,  C,  and  D  in  the  root  segment 
of  the  library  which  subsequently  appear  in  the  .STB  file  as 
def ini  t ions  . 

TKB  resolves  the  definitions  for  symbol  C  directly  to  the  actual  entry 
point.  TKB  resolves  the  definitions  for  symbols  B  and  D  to  autoload 
vectors  that  it  includes  in  each  referencing  task. 


5.1.4.3  Options  for  Use  in  Overlaid  Shared  Regions  -  Certain  options 
may  prove  useful  to  you  when  building  and  linking  shared  regions  to  a 
task.   They  are  described  next. 

GBLDEF  —  You  can  declare  the  definition  of  a  symbol  by  means  of  the 
GBLDEF  option.   The  syntax  of  this  option  is: 

GBLDEF=  symbol-name:symbol-value 

where  symbol-name  is  a  1-  to  6-  character  Radix-50  name  of  the  defined 
symbol  and  symbol-value  is  an  octal  numbei  in  the  range  of  0  through 
177777  assigned  to  the  synbol .  This  option  is  frequently  used  in  the 
TKB  build  file  for  a  task  or  shared  region  to  allow  you  to  alter  the 
value  of  a  global  symbol  that  resides  in  a  module.  This  saves  you  the 
trouble  of  reassembling  the  source  code  for  a  module  if  changes  are 
necessary . 
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GBLINC  —  By  means  of  this  option,  you  force  TKB  to  include  the 
specified  symbols  in  the  .STB  file  beiug  created  by  the  linking 
process  in  which  this  option  appears.   The  syntax  of  this  option  is: 

GBL I NC= symbol -name, symbol -name , . . . , symbol -name 

where  symbol-name  is  the  symbol  or  symbols  to  be  included.  Use  this 
option  when  you  want  to  force  particular  modules  to  be  linked  to  the 
task  that  references  this  library.  The  global  symbol  references 
specified  by  this  option  must  be  satisfied  by  some  module  or  GBLDEF 
specification  when  you  build  the  task. 

GLBREF  --  You  can  force  the  inclusion  of  a  global  reference  in  the 
root  segment  of  the  shared  region  by  means  of  the  GBLREF  option.  In 
this  way,  the  necessary  autoload  vectors  and  definitions  can  be 
generated  without  explicitly  including  such  references  in  an  object 
module.   The  syntax  of  the  option  is: 

GBLREF= [ ,name [ ,name . . . ] ) 

where  the  name  consists  of  from  one  to  six  Radix-50  characters.  If 
the  definition  resides  within  an  autoloadable  segment,  TKB  constructs 
an  autoload  vector  and  includes  it  in  the  symbol  definition  file.  If 
the  definition  is  not  autoloadable,  TKB  obtains  the  real  value  and 
defines  it  in  the  root  segment.  No  global  symbol  appears  in  the  .STB 
file  unless  the  symbol  is  either  defined  in  the  root  segment  or  is 
referenced  in  the  root  segment  and  defined  elsewhere  in  the  overlay 
structure. 

GBLXCL  —  You  can  exclude  a  symbol  or  symbols  from  the  symbol 
definition  file  of  a  shared  region  by  means  of  the  GBLXCL  option.  The 
syntax  of  this  option  is: 

GBLXCL= symbol -name, symbol -name, . . . , symbol -name 

where  symbol-name  is  the  symbol  or  symbols  to  be  excluded.  You  can 
use  this  option  when  you  do  not  want  the  task  to  be  aware  of  specific 
symbols  within  the  library.  This  option  is  particularly  useful  when 
you  cluster  overlaid  libraries  together  (see  the  CLSTR  option  in 
Chapter  11  and  the  Cluster  Libraries  section  in  this  chapter). 


5.1.4.4   Autoload  Vectors  and  .STB  Files  for  Overlaid  Shared  Regions  - 

When  TKB  builds  a  task  image  file  containing  memory-resident  overlays, 
TKB  allocates  autoload  vectors  in  the  task  image.  If  the  task  links 
to  a  shared  region,  autoload  vectors  for  the  shared  region  are  also 
allocated  in  the  task  image.  TKB  allocates  the  autoload  vectors  in 
the  task's  root  segment,  but  not  in  the  shared  region.  Therefore,  the 
shared  region  cannot  reference  unloaded  (unmapped)  segments  of  its 
overlay  structure. 

When  the  task  executes,  the  shared  region  is  effectively  part  of  the 
task.  In  fact,  when  the  task  loads  overlay  segments,  it  makes  no 
distinction  between  overlay  segments  of  the  task  and  those  of  the 
shared  region.  They  are  loaded  as  needed  in  a  procedure  that  is 
transparent  insofar  as  the  execution  of  the  task  is  concerned. 

For  the  Fast  Task  Builder  (FTB)  and  older  versions  of  TKB  that  do  not 
support  overlaid  I-  and  D-space  tasks,  each  autoload  vector  in  the 
shared  region's  .STB  file  is  allocated  in  the  root  of  the  task  being 
linked  to  the  region,  whether  -'•r  not  the  entry  point  is  ref'?<'enced  by 
the  task. 
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However,  if  you  use  a  version  of  TKB  that  supports  overlaid  I-  and 
D-space  tasks  and  the  library  was  built  with  one  of  these  versions, 
TKB  allocates  autoload  vectors  in  the  root  of  the  task  only  for  those 
autoloadable  entry  points  in  the  library  that  the  task  references. 
The  .STB  file  contains  ISD  records  that  allow  TKB  to  c.  lete 
dynamically  autoload  vectors  when  linking  the  task  to  the  library. 
TKB  ignores  the  autoload  vectors  in  the  .STB  file  if  the  ISD  records 
are  pre&ent.  Therefore,  tasks  that  link  to  overlaid  shared  regions 
and  that  are  built  with  newer  versions  of  TKB  tend  to  be  smaller  and 
use  less  victual  address  space  than  those  that  are  built  by  FTB  ex 
older  versions  of  TKB. 


NOTE 

Libraries  created  with  older  versions  of 
TKB  do  not  have  the  ISD  records  in  the 
.STB  file  that  newer  versions  of  TKB  use 
to  include  autoload  vectors  in  the  task 
from  tiie  .STB  file.  Therefore,  TKB  must 
create  autoload  vectors  for  every  entry 
point  in  the  library. 

If  you  are  using  one  of  these  older 
libraries  and  you  are  linking  an  I>  and 
D-space  task  to  it,  TKB  will  fji' <»  you 
the  fatal  error  message: 

"Module  module-name  contain'^ 
incompatible  autoload  vectors." 

This  message  occurs  because  the  .STB 
file  contains  conventional  autoload 
vectoirs  that  are  not  usable  by  an  I-  and 
D-space  task. 


Only  those  global  symbols  defined  or  referenced  in  the  root  segment  of 
the  shared  region  appear  in  the  .STB  file.  The  .STB  file  also 
contains  the  data  base  required  by  the  overlay  run-time  system  in 
relocatable  object  module  format.   This  data  base  includes: 

e  All  autoload  vectors 

•  Segment  tables  (linked  as  described  in  Appendix  B) 

•  Window  descriptors 

•  A  single  region  descriptor 

The  overlay  structure,  as  reflected  in  the  segment  table  linkage,  is 
preserved  and  conveyed  to  the  referencing  task  by  the  .STB  file. 
Thus,  path  loading  for  the  shared  region  can  occur  exactly  as  it  does 
within  a  task.  Aside  from  address  space  restrictions,  there  are  no 
limitations  on  the  overlay  structures  that  can  be  defined  for  a  shared 
region. 
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5.1.5   Run-Time  Support  for  Overlaid  Shared  Regions 

Memory-resident  overlays  within  a  shared  region  require  little 
additional  support  from  the  overlay  run-time  system.  The  shared 
region  overlay  data  base  that  is  linked  within  the  image  of  the 
referencing  task  has  a  structure  that  is  identical  to  the  equivalent 
data  created  for  an  overlaid  task.  Therefore,  memory-resident 
overlays  within  the  shared  region  are  indistinguishable  from 
memory-resident  overlays  that  form  a  part  of  the  task  image.  The  only 
additional  processing  is  that  required  to  attach  the  shared  region  and 
obtain  its  identification  for  use  by  the  mapping  directives. 

Once  this  initialization  is  complete,  all  further  processing  is 
identical  to  memory-resident  overlay  processing  performed  on  task 
overlays . 

Several  restrictions  apply  to  shared  regions  existing  as 
memory-resident  overlays: 

•  A  shared  region  cannot  use  the  autoload  facility  to  reference 
memory-resident  overlays  within  itself  or  any  other  region. 
If  each  segment  is  uniquely  named,  overlays  can  be  mapped 
through  the  manual  load  facility. 

•  Named  program  sections  in  a  shared  region  overlay  segment 
cannot  be  referenced  by  the  task.  If  reference  to  the  storage 
is  required,  such  sections  must  be  included  in  the  root 
segment  of  the  region  (with  resultant  loss  of  virtual  address 
space) . 

•  For  FTB,  and  libraries  built  with  versions  of  TKB  that  do  not 
support  I-  and  D-space  overlaid  tasks,  the  number  of  autoload 
vectors  is  independent  of  the  entry  points  actually 
referenced.  The  maximum  number  of  vectors  will  be  allocated 
within  each  referencing  task.  In  some  cases  the  size  of  the 
allocation  will  be  large. 

•  There  is  an  overhead  of  six  instructions  per  autoload  call, 
even  when  the  segment  is  mapped.  The  overhead  is  seven 
instructions  for  an  overlaid  I-  and  D-  space  task. 

As  implied  by  the  previous  items,  great  care  must  be  exercised  if  an 
efficient  memory-resident  overlay  structure  for  library  routines  such 
as  the  FORTf^AN  IV  GTS  is  to  be  implemented. 


5.1.6   Linking  to  a  Shared  Region 

When  you  build  a  task  that  links  to  a  shared  region,  you  must  indicate 
to  TKB  the  name  of  the  shared  region  and  the  type  of  access  the  task 
requires  to  it  (read/write  or  read-only).  In  addition,  if  the  shared 
region  is  position  independent,  you  can  specify  which  APR  TKB  is  to 
allocate  for  mapping  the  region  into  the  task's  virtual  address  space. 
Four  options  are  available  for  this  action: 

•  RESLIB  (resident  library) 

•  RESCOM  (resident  common) 

•  LIBR  (system-owned  resident  library) 

•  COMMON  (system-owned  resident  common) 
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RESLIB  and  RESCOM  accept  a  complete  file  specification  as  one  of  their 
arguments.  Thus,  you  can  specify  a  device  and  UFD  indicating  to  TKB 
the  location  of  the  region's  image  file  and,  by  implication,  its 
symbol  definition  file,  (Refer  to  Chapter  1  for  more  information  on 
file  specifications  and  defaults.) 

LIBR  and  COMMON  accept  a  1-  to  6-character  name.  When  you  specify 
either  of  these  options,  the  shared  region's  image  file  and  symbol 
definition  file  must  reside  under  UFD  [1,1]  on  device  LEO:. 

The  RESLIB  and  RESCOM  options  require  that  all  users  of  the  shared 
region  know  the  UFD  under  which  the  shared  region's  image  file  and 
.STB  file  reside.  The  LIBR  and  COMMON  options  require  only  that  the 
users  of  the  shared  region  know  the  name  of  the  shared  region.  Whe" 
you  specify  either  LIBR  or  COMMON,  by  default,  TKB  expects  to  find  the 
shared  region's  image  and  .STB  files  on  device  LB:   under  UFD  [IfH- 

All  four  options  accept  two  additional  arguments: 

•  The  type  of  access  that  the  task  requires  (RO  or  RW) . 

•  The  first  APR  that  TKB  is  to  allocjte  for  mapping  the  region 
into  the  task's  virtual  address  space.  As  stated  earlier, 
this  argument  is  valid  only  when  the  shared  region  is  position 
independent. 

When  you  specify  any  of  these  options,  TKB  expects  to  find  a  symbol 
definition  file  of  the  same  name  as  that  of  the  shared  region,  but 
with  an  extension  of  .STB,  on  the  same  device  and  under  the  same  UFD 
as  those  of  the  shared  region's  image  file. 

The  syntax  of  these  options  is  given  in  Chapter  11. 

When  TKB  builds  a  task,  it  processes  first  any  options  that  appear  in 
the  TKB  command  sequence.  When  TKB  processes  one  of  the  four  options 
above,  it  locates  the  disk  image  of  the  shared  region  named  in  the 
option.  The  disk  image  of  a  shared  region  does  not  have  a  header,  but 
it  does  have  a  label  block  that  contains  the  allocation  information 
about  the  shared  region  (for  example,  its  base  address,  load  size,  and 
the  name  of  the  partition  for  which  it  was  built).  TKB  extracts  this 
data  from  the  shared  region's  label  block  and  places  it  in  the  LIBRARY 
REQUEST  section  of  ttie  label  block  tor  the  referencing  task. 

The  .STB  file  associated  with  the  shared  region  is  an  object  module 
file.  TKB  processes  it  as  an  input  file.  If  the  shared  region  is 
position  independent,  its  .STB  file  contains  program  section  names, 
attributes,  and  lengths.  However,  the  program  section  names  are 
flagged  within  the  file  as  "library"  program  sections  and  TKB  does  not 
add  their  allocations  to  the  task  image  it  is  building. 

If  the  task  links  to  only  one  shared  region,  and  if  neither  the  shared 
region  nor  the  task  that  links  to  it  contain  memory-resident  overlays, 
the  Task  Builder  allocates  two  window  blocks  in  the  header  of  the 
task.  (Overlays  are  described  in  Chapter  3.)  When  the  task  is 
installed,  the  INSTALL  processor  will  initialize  these  window  blocks 
as  follows: 

•  Window  block  0  will  describe  the  range  of  virtual  addresses 
(the  window)  for  the  task  region. 

•  Window  block  1  will  describe  the  window  for  the  shared  region. 
Figure  5-6  shows  the  window-to-region  relationship  of  such  a  task. 
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Figure    5-6      Windows    for   Shared    Region    and    Referencing   Task 
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A  shared  region  need  not  be  installed  before  a  task  that  links  to  it 
is  built.  The  .STB  file  that  you  specify  when  you  build  the  shared 
region  contains  all  the  information  required  by  TKB  to  resolve 
references  from  within  a  task  to  locations  within  the  shared  region. 
The  only  requirement  is  that  you  install  a  shared  region  before  you 
install  a  task  that  links  to  it. 

Unless  you  use  the  /LI  switch,  there  is  a  restriction  on  the  way  TKB 
processes  tasks  that  link  to  relocatable  shared  regions.  TKB  places 
all  program  section  names  into  its  internal  control  section  table. 
The  program  section  names  include  those  from  the  .STB  file  of  the 
shared  region  as  well  as  those  from  the  other  input  modules.  A 
conflict  car.  arise  when  building  a  task  that  contains  program  sections 
of  the  same  name  as  those  in  the  shared  region  to  which  the  task 
links.  The  conflict  arises  because  TKB  tries  to  add  the  program 
section  allocation  in  the  task  to  the  already  existing  allocation  for 
the  program  section  of  the  same  name  in  the  region.  This  is  not 
possible  because  the  region's  image  has  already  been  built,  is  outside 
the  address  space  of  the  task  currently  being  built,  and  cannot  be 
modified.  Therefore,  to  avoid  this  conflict,  the  program  section 
names  within  a  task  that  links  to  a  relocatable  shared  region  must 
normally  be  unique  with  respect  to  program  section  names  within  the 
shared  region. 

TKB  displays  an  error  message  under  the  following  conditions: 

•  A  program  section  in  the  task  and  a  program  section  in  the 
shared  region  have  the  same  name. 

•  The  program  section  in  the  task  contains  data. 

•  TKB  tries  to  initialize  the  program  section  in  vhe  task. 

The  error  message  occurs  when  TKB  tries  to  store  data  in  an  image 
outside  the  address  limits  of  the  task  it  is  building.  It  this 
conflict  occurs,  TKB  prints  the  following  message: 

TKB--*DIAG*-load  addr  out  of  range  in  module  module-name 

One  exception  to  the  above  restriction  develops  when  all  of  the 
following  conditions  exist: 

•  Both  program  sections  (in  the  shared  region  and  in  the 
referencing  task)  have  the  (D)  data  and  the  OVR  (overlay) 
attributes . 

•  The  program  section  in  the  task  is  equal  to  or  shorter  than 
the  program  section  in  the  shared  region. 

•  The  program  section  in  the  task  does  not  contain  data. 

When  all  of  these  conditions  exist,  there  is  nothing  to  be  initialized 
within  the  shared  region.  TKB  binds  the  base  address  of  the  program 
section  in  the  task  to  the  base  address  of  the  program  section  in  the 
shared  region.  If  the  program  section  in  the  task  contains  global 
symbols,  TKB  assigns  addresses  to  them  that  reflect  their  location 
relative  to  the  beginning  of  the  program  section.  You  can  use  this 
technique  to  establish  symbolic  offsets  into  resident  commons. 
Examples  5-1  and  5-2  in  the  following  sections  illustrate  how  to 
establish  these  offsets. 
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5.1.7   Number  and  Size  of  Shared  Regions 


The  number  of  shared  regions  to  which  a  task  can  link  is  a  function  of 
the  number  of  window  blocks  required  to  map  the  task  and  the  regions. 
In  an  RSX-llM  operating  system,  if  a  task  is  4K  words  or  less,  and 
each  shared  region  to  which  the  task  links  is  4K  words  or  less,  then  a 
nonpr i vi leged  task  can  access  as  many  as  seven  shared  regions. 


In  an  RSX-llM-PLUS  operating  system,  if  a  task  is  4K  words  or  less, 
and  eacli  shared  region  to  which  the  task  links  is  4K  words  or  less,  a 
nonpr ivileged  task  can  refer  to  as  many  as  15  shared  regions:  7  in 
user  mode  and  8  in  supervisor  mode.  (Supervisor-mode  libraries  are 
described  in  Chapter  8.) 


5.1.8   Example  5-1:   Building  and  Linking  to  a  Common  in  MACRO-11 

The  text  in  this  section  and  the  figures  associated  with  it  illustrate 
the  development  of  a  MACRO-11  posi t ion- independent  resident  common  and 
the  development  of  two  MACRO-11  tasks  that  share  the  common.  The 
steps  in  building  a  pos i t ion- i ndependent  common  can  be  summarized  as 
f ol lows : 

1.  You  create  a  source  file  that  allocates  the  amount  of  space 
required  for  the  common.  In  MACRO-11,  either  of  the 
assembler  directives,  .BLKB  or  .BLKW,  provide  the  means  of 
allocating  this  space. 

2.  You  assemble  the  source  file. 

3.  You  build  the  assembled  module,  specifying  both  a  task  image 
file  anu  a  symbol  definition  file. 

You  specify  the  /-HD  (no  header)  switch  and  declare  the 
common  with  /CO.  You  specify  the  common  to  be  position 
independent  with  the  /PI  switch. 

Under  options  you  specify: 

STACK=0 
PAR=parname 

The  parname  in  this  PAR  option  is  the  name  of  the  partition 
in  which  the  common  is  to  reside.  (The  /HD  and  /PI  switches 
and  the  STACK  and  PAR  options  are  described  in  Chapter  10.) 

If  your  system  is  an  RSX-llM  system,  the  common  must  reside 
within  a  common  partition  of  the  same  name  as  that  of  the 
common . 

If  your  system  is  an  RSX-llM-PLUS  system,  the  common  can 
reside  within  any  partition  large  enough  to  hold  it. 

4.  You  install  the  common. 

Example  5-1  below  sh  -s  a  MACRO-11  source  file  that,  when  assembled 
and  built,  creates  a  pos i t i on- i ndependent  resident  common  area  named 
MACCOM.  The  common  area  consists  of  two  program  sections  named  COMl 
and  COM2,  respectively.  Each  program  section  is  512(decimal)  words 
long . 
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Example  5-1,  Part  1   Common  Area  Source  File  in  MACRO-11 

.TITLE  MACCOM 

t 
I 

;  COMl  -  512  WORDS 

;  COM2  -  512  WORDS 

; 

.PSECT  C0M1,RW,D,GBL,REL,0VR 
.BLKW  512. 

.PSECT  C0M2,RW,D,GBL,REL,0VR 
•BLKW  512. 

.END 

Once  this  common  has  been  assembled,  the  Task  Builder  command  sequence 
shown  below  can  be  used  to  build  it. 

>TKB 

TKB>MACCOM/PI/-HD/CO,MACCOM/-SP,MACCOM^MACCOM 

TKB>/ 

Enter  Options: 

TKB>STACK=0 

TKB>PAR=MACCOM:0 :4000 

TKB>// 

This  command  sequence  directs  TKB  to  build  a  position-independent 
(/PI),  headerless  (/-HD)  common  image  file  named  MACCOM. TSK.  It  also 
specifies  that  the  Task  Builder  is  to  create  a  map  file,  MACCOM. MAP, 
and  a  symbol  definition  file,  MACCOM. STB.  TKB  creates  all  three 
files  --  MACCOM. TSK,  MACCOM. MAP,  and  MACCOM. STB  —  on  device  SY: 
under  the  UFD  that  corresponds  to  the  terminal  UIC.  Because  /-SP  is 
attached  to  the  map  file,  TKB  will  not  spool  a  map  listing  to  the  line 
printer . 

Under  options,  STACK=0  suppresses  the  stack  area  in  the  common's 
image.  The  PAR  option  specifies  that  the  common  area  will  reside 
within  a  common  partition  of  the  same  name  as  that  of  the  common, 
MACCOM.  In  addition,  the  parameters  in  the  PAR  option  specify  a  base 
of  0  and  a  length  of  4000  octal  bytes  for  the  common.  (Refer  to 
Chapters  10  and  11  for  descriptions  of  the  switches  and  options  used 
in  this  example.) 

Example  5-1,  Part  2  shows  the  map  resulting  from  this  command 
sequence. 

The  task  attributes  section  of  this  map  reflects  the  switches  and 
options  of  the  command  string.  It  indicates  that  the  common  resides 
in  a  partition  named  MACCOM,  that  it  was  built  under  terminal  UIC 
[7,62],  that  it  is  headerless  and  position  independent,  and  that  it 
requires  one  window  block  to  map.  The  total  length  of  the  common  is 
1024 (decimal)  words  and  its  address  limits  range  from  0  to 
3777 (octal).  The  common  image  (that  portion  of  the  disk  image  file 
that  eventually  will  be  read  into  memory)  begins  at  file-relative  disk 
block  2  0  •  The  last  block  in  the  file  is  file-relative  disk  block 
5  ©  and  the  common  image  is  four  blocks  long  Q  . 

The  memory  allocation  synopsis  details  the  Task  Builder's  allocation 
for  and  the  attributes  of  the  program  sections  within  the  common.  For 
example,  reading  from  left   to   right,   the   map   indicates   that   the 
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program  sectioii  COMl  permits  read/write  access,  that  it  contains  drta, 
nnd   tnat   its   scope   is   global.    It   also   indicates   that  COMl  is 
relocatable  and  that  all  contributions  to  COMl   are   to   be 
has 


overlaid . 


relocatable  and  that  all  contr iDut ions  to  c:OMl   are  to   be   overlaid. 

Because   COMl   has   the  overlay  attribute,  the  total  allocation  for  it 

will  be  equal  to  the  largest  allocation  request  from  the  modules   that 

contribute    to    it.     (For   more   information   on  program   section 
attributes,  see  Chapter  2.) 


Continuing  to  the  right,  the  first  6-digit 
address,  which  is  0  O.  The  next  two  digits 
octal  and  decimal,  respectively. 


number   is   COMl's   base 
are  its  length  (bytes)  in 


The  next  line  down  lists  the  first  object  module  that  c  .itr ibutes  to 
COMl.  In  this  case  there  is  only  one:  the  module  MACCOM  from  the 
file  MACCOM. OBJ;  1 .  The  numbers  on  this  line  indicate  the  relativ»i 
base  address  of  the  contribution  and  the  length  of  the  contribution  in 
octal  and  decimal  0  .  If  there  had  been  more  than  one  module  input  to 
TKB  that  contained  a  program  section  named  COMl,  TKB  would  have  listed 
each  module  and  its  contribution  in  this  section. 

Notice  that  there  is  a  program  section  named  .  LLK.  shown  on  the  map 
just  above  the  field  for  COMl.  This  is  the  "blank"  program  section 
that  is  created  automatically  by  the  language  translators.  The 
attribute  shown  are  the  default  attributes.  The  allocation  for 
.  BLK.  3  0  because  the  program  sections  in  MACCOM  were  explicitly 
declared.  If  the  program  sections  had  not  been  explicitly  dec;  red, 
all  of  the  allocation  for  the  common  would  have  been  within  this 
program  section. 


Example  5-1,  Part  2   Task  Builder  Map  for  MACCOM. TSK 


MACCOM. TSK;1 


Memory  allocation  map   TKB  M40.10 
17-NOV-82    16:05 


Page  1 


Partition  name  :  MACCOM 

Identification  : 

Task   UIC       :  [7,62] 

Task  attributes:  -HD,PI 

Total  address  windows:  1. 

Task   image   size   :  1024.  WORDS 

Task  address  limits:  OCOOOO  003777 

R-W  disk  blk  limits:  000002  000005  000004  00004. 

***  Root  segment:  MACCOM O     © 


"V 


• 


R/W  mem   limits:  000000  003777  004000  02048. 
Disk  blk  limits:  000002  000005  000004  00004. 


Memory  allocation  synopsis: 
Section 


BLK. :  (RW, I,LCL,REL,CON)  000000  000000  00000. 


COMl   : (RW,D,GBL,REL,OVR) 
COM2   : (RW,D,GBL,REL,OVR) 


000000  002000  01024. 
OO2OO0  01024. 


/ 

Q 


000000 
002000 
002000 


002000 
002000 


01024. 
01024. 


Title 

•MAIN. 
.MAIN. 


Ident  File 


MACCOM. OB J; 1 
MACCOM. OB J, -1 


(continued  on  next  page) 
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Example    5-1,    Part    2    (Cont.)       Task    Builder    Map    for    MACCOM.TSK 


**•    Task    builder    st.itistics: 

Total    work    file    references:     183. 

Work      f  i le      reads :    0. 

Work      file    writes:    0. 

Size   of    core    pool:    7086.    WORDS    (27.    PAGES) 

Size   of    work    file:    768.    WORDS    (3.    PAGES) 

Elapsed    t ime : 00 : 00 : 05 


Figure  5-7  is  a  diagram  that  represents  the  disk  image  file  for 
MACCOM.  The  circled  numbers  in  Figure  5-7  correspond  to  the  circled 
numbers    in    Example    5-1,    Part    2. 


RELATIVE 
DISK  BLOCK 
NUMBERS 


RELATIVE 

LOAD 

ADDRESSES 


000005         — 


000004  _ 


000003  — 


•-       000002  — 


000001  — 


000000         — 


002000 


—       000000       J 


-    002000  (BYTES) 


^ 


DISK  IMAGE  FILE 
Figure  5-7   Allocation  Diagram  for  MACCOM.TSK 


Once  you  have  built  MACCOM,  you  can  install  it.  If  your  system  is  an 
RSX-llM  systcrr?.  the  common  is  loaded  into  memory  when  you  install  it. 

If  your  system  is  an  RSX-llM-PLUS  system,  it  remains  there  until  you 
explicitly  remove  it  with  the  MCR  command  REMOVE.  The  common  will  not 
be  loaded  until  either  one  of  tht>  following  occurs: 

•  A  task  that  is  linked  to  it  is  run. 

•  You  explicitly  fix  the  common  in  memory  with  the  MCR  command 
FIX, 
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Example  5-1,  Parts  3  and  4  show  two  programs:  MCOMl  and  MC0M2, 
respectively.  Both  of  these  programs  reference  the  common  area  MACCOM 
created  above.  MCOMl  in  Example  5-1,  Part  3  accesses  the  COMl  portion 
of  MACCOM.  It  inserts  into  the  first  10  words  of  COMl  the  numbers  1 
through  10  in  ascending  order.  It  then  issues  an  Executive  directive 
request  for  the  task  MC0M2  and  suspends  itself. 


When  MC0M2  runs,  it  adds  together  the  integers  left  in  COMl  by  MCOMl 
and  leaves  the  sum  in  the  first  word  of  COM2.  It  then  issues  a  resume 
directive  for  MCOMl  and  exits. 

When  MCOMl  resumes,  it  retrieves  the  answer  left  in  COM2  and  calls  the 
system  library  routine  $EDMSG  (edit  message)  to  format  the  answer  for 
output  to  device  TI : . 


All  of  the  Executive  directives  for   both   programs 
QIOW$S,   RSUM$C,   and   EXIT$S)   are   documented   in 
Executive  Reference  Manual .   The   system   library   routine 
documented  in 


(RQST$C,   SPND$S, 

the   RSX-llM-PLUS 

$EDMSG   Ts 


the  IAS/RSX-11  System  Library  Routines  Reference  Manual 


Example  5-1,  Part  3   MACRO-11  Source  Listing  for  MCOMl 


.TITLE   MCOMl 
.IDENT   /Ol/ 


.MCALL   EXIT$S,SPNDSS,RQST$C,0IOWSS 


OUT: 

FORMAT: 

MES: 


.BLKW 
.ASCIZ 
.ASCII 
LEN  =  , 
.EVEN 


100. 

/THE  RESULT  IS  %D./ 
/ERROR  FROM  REQUEST/ 
-  MES 


SCRATCH  AREA 


INT: 


PSECT  - 
COMMON. 

•PSECT 
.BLKW 


COMl  IS  USED  TO  ACCESS  THE  FIRST  512.  WORDS  OF  THE 


COMl, GEL, 0VR,D 
10. 


ANS: 


PSECT  -  COM2  IS  USED  TO  ACCESS  THE  SECOND  512, 
COMMON.  IT  WILL  CONTAIN  THE  RESULT 

.PSECT   COM2, GEL, OVR.D 
.BLKW    1 


WORDS  OF  THE 


START: 


.PSECT 

MOV 
MOV 
MOV 


#10. ,R0 

#1,R1 

#INT,R3 


NUMBER  OF  INTEGERS  -"0  SUM 
START  WITH  A  1 

PLACE  VALUES  IN  1ST  10  WORDS 
OF  COMMON 


(continued  on  next  page) 
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Example    5-1,    Part    3    (Cont.)      MACRO-U    Source    Listing    for    MCOMl 


109: 


ERKl! 


MOV 

INC 

DEC 

BNE 

RQSTSC 

BCS 

SPND$S 

MOV 

MOV 

MOV 

CALL 

QIOWSS 

EXIT$S 


Rl,  (R3)  + 

Rl 

RO 

10$ 

MC0M2 

ERRl 

#OUT,R0 
♦FORMAT, Rl 
»A(JS,R2 
$EDMSG 


#IO.WVB,i5,#l,,,,<|OUT,Rl,#40> 


INITIALIZE  COMMON 

NEXT  INTEGER 

ONE  LESS  TIME 

TO  INITIALIZE 

REQUEST  THE  SECOND  TASK 

REQUEST  FAILED 

WAIT  FOR  MC0M2  TO  SUM  THE  INTEGERS 

ADDRESS  OF  SCRATCH  AREA 

FORMAT  SPECIFICATION 

ARGUMENT  TO  CONVERT 

DO  CONVERSION 


QIOWSS   »IO.WVB,#5,»1,,,,<#MES,|LEN,»40> 

EXITSS 

.END     START 


Example  5-1,  Part  4   MACRO-U  Source  Listing  for  MC0M2 


MES! 


.TITLE 
,  IDENT 


.ASCII 
LEN  =  , 
•  EVEN 


MC0M2 

/Ol/ 


.MCALL   EXIT$S,QIOW$S,RSUMSC 


/ERROR  FROM  RESUME/ 
-  MES 


PSECT  - 
COMMON, 


COMl  IS  USED  TO  ACCESS  THE  FIRST  10.  WORDS  OF  THE 


.PSECT   C0M1,GBL,0VR,D 
INT:      .BLKW    10. 


ANS; 


PSECT  - 
COMMON. 

. PSECT 
.BLKW 


COM2  IS  USED  TO  ACCESS  THE  SECOND  10.  WORDS  OF  THE 
IT  WILL  CONTAIN  THE  RESULT 

C0M2,GBL,0VR,D 

1 


.PSECT 


START: 


10$; 


ERR: 


MOV 
MOV 

CLR 
ADD 
DEC 
BNE 

RSUM$C 

BCS 

EXIT$S 

QIOW$S 
EXIT$S 
.END 


#10. ,R0 
#INT,R3 

ANS 

{R3)+,ANS 

RO 

10$ 

MCOMl 
ERR 


NUMBER  OF  INTEGERS  TO  SUM 

PLACE  VALUES  IN  1ST  10  WORDS 

OF  COMMMON 

INITIALIZE  ANSWER 

ADD  IN  VALUES 

ONE  LESS  VALUE 

TO  SUM 

RESUME  MCOMl 
RESUME  FAILED 


#IO.WVB,#5,#1,,,,<#MES,#LEN,#40> 
START 
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Note  that  both  tasks  MCOMl  and  MC0M2  contain  .PSECT  declarations 
establishing  program  section  names  that  are  the  same  as  program 
section  names  within  the  position-independent  common  to  which  the  task 
is  linked  (MACCOM) .  As  stated  earlier,  in  most  circumstances  this 
would  be  illegal.  In  this  application,  however,  the  .PSECT  dire>.tives 
have  been  placed  into  the  tasks  to  establish  symbolic  offsets  in  the 
resident  common.  When  either  task  is  built,  TKB  assigns  to  the  symbol 
INT:  the  base  address  of  program  section  COMl,  and  to  the  symbol  ANS: 
the  base  address  of  program  section  COM2.  Figure  S-fl  illustrates  this 
assignment . 


ANS 


I--- 


ANS 


INT 


INT: 


COM2 


COM  1 


Figure  5-8   Assigning  Symbolic  References  within  a  Common 

Once  you  have  assembled  MCOMl  and  MC0M2,  you  can  build  them   with   the 
following  TKB  command  sequences: 

>TKB 

TKB>MC0M1,MC0M1/-SP=MC0M1 

TKB>/ 

Enter  Options: 

TKB>  RESCOM=MACCOM/RW 

TKB>// 


>TKB 

TKB5MCOM2 ,MCOM2/-SP=MCOM2 

TKB>/ 

Enter  Options: 

TKB>  RESCOM=M ACCOM/RW 

TKB>// 


Under  options  in  both  of  these  command  sequences,  the  RESCOM  option 
tells  TKB  that  these  programs  intend  to  reference  a  common  data  area 
named  MACCOM  and  that  the  tasks  require  read/write  access  to  it. 
Because  the  RESCOM  option  is  used,  TKB  expects  to  find  the  image  file 
and  the  symbol  definition  file  for  the  common  on  device  SY:  under  the 
UFD  that  corresponds  to  the  terminal  UIC.  In  addition,  because  the 
optional  APR  specification  was  omitted  from  the  RESCOM  option,  TKB 
allocates  virtual  address  space  for  the  common  starting  with  APR7  in 
both  tasks  (the  highest  APR  available  in  both  tasks). 
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The  TKB  map  foi-  MCOMl  is  shown  in  Example  5-1,  Part  5.  The  map  for 
MC0M2  is  not  essentially  different  from  that  of  MCOMl  and  is  therefore 
not  included  here. 


Example  5-1,  Part  5   Task  Builder  Map  for  MCOMl. TSK 


MCOMl. TSK;1     Memory  allocation  map  TKB  M40.10       Page  1 

ll-DEC-82    16:12 


GEN 

01 

(7,62) 

000274  001273  001000  00512, 

001050 


Partitit   .ame 

Identifiv  .ion 

Task   UIC 

Stac!     limits; 

PRG  xfr  address; 

Total  address  windows:  2. 

Task   image   size   :  1184.  WORDS 

Task  address  limits:  000000  004407 

R-W  disk  blk  limits:  000002  000006  000005  00005. 

***  Root  segment:  MCOMl 


R/W  mem   limits:  000000  004407  004410  02312, 
Disk  blk  limits:  000002  000006  000005  00005. 


Memory  allocation  synopsis: 


Section 


Ident   File 


MCOMl. OB J; 1 
MCOMl, OB J; 1 
MCOMl. Ob J; 1 
MCOMl.OBJ;! 


Task  builder  statistics: 


Total 

Work 

Work 

Size 

Size 


work 

file 

file  writes 
of  core  pool 
of  work  file 


file  references: 
reads:  0. 


1924 


0. 

7086 

1024, 


WORDS 
WORDS 


(27, 
(4. 


PAGES) 
PAGES) 


Elapsed  time:00 :00 :04 
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Note  that  TKB  has  placed  two  window  blocks  in  MCOMl's  header.  When 
MCOMl  is  installed,  the  INSTALL  processor  will  initialize  these  window 
blocks  as  follows: 

•  Window  block  0  will  describe  the  range   of   virtual   addresses 
(the  window)  for  MCOMl's  task  region. 

•  Window  block  1  will  describe  the  window  for  the  shared   region 
MACCOM. 


5.1.9   r.inking  Shared  Regions  Together 

Shared  regions  can  link  to  other  shared  regions.  You  may  find  it 
convenient  to  have  code  in  a  shared  library  and  have  access  to 
routines  in  another  shared  library  to  which  it  links. 

The  following  text  describes,  as  an  example  for  a  mapped  system,  the 
TKB  command  sequence  for  building  a  resident  library  named  FILES. 
That  text  is  followed  by  a  TKB  command  sequence  that  shows  an  example 
of  building  another  resident  library  named  FORCOM  that  links  to  FILEB. 
Following  after  that,  a  TKB  command  sequence  shows  th'  building  of  a 
task  that  links  to  FORCOM.  In  the  TKB  command  sequences  to  follow,  it 
is  assumed  that  you  know  the  contents  of  the  libraries  and  the  task. 
The  examples  show  the  linkage  only. 

The  first  shared  region  to  be  built  is  called  FILEB.  The  library 
FILEB  is  a  position-dependent  library.  You  use  the  /-PI  switch  to 
signify  that  the  library  is  absolute.  You  build  the  library  with  the 
/-HD  switch  to  indicate  that  the  library  has  no  header.  The  /LI 
switch  indicates  that  FILEB  is  to  be  a  shared  library.  The  program 
section  name  of  the  library  is  .  ABS,  which  is  the  only  one  in  the 
library.  FILEB  is  to  be  loaded  into  a  user-controlled  partition  on  a 
mapped  system.  The  name  of  the  partition  in  which  FILEB  resides  has 
the  same  name,  FILEB,  that  you  specify  in  the  PAR  option.  The  PAR 
option  also  specifies  the  base  address  and  the  length  of  the 
partition.  Because  FILEB  is  absolute,  a  base  address  must  be 
specified;  here,  the  base  address  is  160000.  The  length  in  this 
example  is  4K  bytes.  If  neither  the  base  nor  the  length  is  specified, 
TKB  tries  to  determine  the  length.   The  TKB  command  sequence  follows: 

>TKB 

TKB>FILEB/-PI/-HD/LI,FILEB/-SP,FILEB=FILEB.OBJ 

TKB>  ' 

Enter  Options: 

TKB>STACK=0 

TKB>PAR=FILEB: 1600  00: 4  0000 

TKB>// 

The  next  TKB  command  sequence  specifies  a  shared  library  called 
FORCOM.  FORCOM  links  to  the  read-only  library  called  FILEB.  You 
build  FORCOM  with  the  /LI  switch  to  specify  a  library  to  the  Task 
Builder.  FORCOM  is  relocatable.  You  specify  in  the  RESLIB  option 
that  the  resident  library  to  which  FORCOM  links  is  called  FILEB.    The 
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access  required  is  read-only,  which  /RO  specifies  in  the  RESLtB  option 

line.   The  TKB  command  sequence  follows:  j^^ 

>TKB  ^^ 

TKB>  F'ORC0M/-HD/L  I  /PI  ,  FORCOM/-SP ,  FORCOM-  FORCOM  .  OBJ 

TKB>/ 

Enter    Options: 

tkb>stack=0 

tkb>par=forcom:0:4000 

tkb>re:slib«fileb/ro 

TKB>// 

The  next  TKB  command  sequence  builds  the  task  and  specifies  that  the 
task  links  to  the  library  called  FORCOM.  The  RESLIB  option  line 
specifies  th3  link  to  the  resident  library  called  "ORCOM. 

>TKB 

TKB>  FOTASK , FOTASK/-SP, FOTASK=  FOTASK . OBJ 

TKB>/ 

Enter    Options: 

TKB>RESLI3=F0RC0M/RW 

TKB>// 

Build  the  libraries  before  you  bi i id  the  task,  and  install  the 
libraries  before  you  run  or  install  the  task.  See  Chapters  10  arid  11 
for  a  description  of  the  /PI,  /HD,  /CO,  and  /LI  switches  and  the  PAR, 
RESCOM,  and  RESLIB  options. 


5.1.10   Example  5-2:   Buildinq  and   Linking   to   a   Device  Common   in 
MACRO- 11 

A  device  common  is  a  special  type  of  common  that  occupies  physical 
addresses  on  the  I/O  page.  When  mapped  into  the  virtual  address  space 
of  a  task,  a  device  common  permits  the  task  to  manipulate  peripheral 
device  registers  directly. 

NOTE 

Because  any  access  to  the  I/O  page  is 
potentially  hazardous  to  the  running 
system,  you  must  exercise  extreme 
caution  when  working  with  device 
commons. 

The  remaining  text  in  this  section  and  the  figures  associated  with  it 
illustrate  the  development  and  use  of  a  device  common.  Example  5-2, 
Part  1  shows  an  assembly  listing  for  a  position-independent  device 
common  named  TTCOM.  When  installed,  TTCOM  will  map  the  control  and 
data  registers  of  the  console  terminal.  Its  physical  base  address 
will  be  777500. 
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Example  5-2,  Part  1   Assembly  Listing  for  TTCOM 


•TITLE 

TTCOM 

.PSECT 

TTCOM,GBL,D,RW,OVR 

.«.+60 

$RCSR: 

:   .BLKW 

1 

$RBUF: 

:   .BLKW 

1 

$XCSR: 

:   .BLKW 

1 

$XBUF: 

:   .BLKW 
.END 

1 

The  PDP-11  Peripherals  Handbook  defines  the  control  and  data   register 

addresses   for   the   console   terminal.  In   Example  5-2,  Part  1,  the 

register  addresses  and  the  symbol  names  that  correspond  to  them  are  as 
follows: 


Register 

Address 

Symbol 

Keyboard  Status 

777560 

$RCSR 

Keyboard  Data 

777562 

$RBUF 

Printer  Status 

777564 

$XCSR 

Printer  Data 

777566 

$XBUF 

The  double  colon  (::)  following  each  symbol  in  Example  5-2,  Part  1 
establishes  the  symbol  as  global.  The  first  symbol,  RCSR,  is  offset 
from  the  beginning  of  TTCOM  by  60 (octal)  bytes.  Each  symbol 
thereafter  Is  one  word  removed  from  the  symbol  that  precedes  it. 
Thus,  when  TTCOM  is  Installed  at  777500,  each  symbol  will  be  located 
at  its  proper  address. 


Once  you  have  assembled  TTCOM,  you  can  build  it 
TKB  command  sequence: 


using   the   following 


>TKB 

TKB>LB: [ 1 , 1 ] TTCOM/-HD/PI , LB : [1 , 1 ] TTCOM/-WI/SP , LB : [1 , 1 ] TTCOM=TTCOM 

TKB>/ 

Enter  Options: 

TKB>STACK=0 

TKB>PAR=TTCOM:0: 100 

TKB>// 

This  command  sequence  directs  TKB  to  create  a  common  image  named 
TTCOM. TSK  and  a  symbol  definition  file  named  TTCOM. STB.  TKB  places 
both  files  on  device  LB:  under  UFD  [1,1].  The  command  sequence  also 
specifies  that  TKB  is  to  spool  a  map  listing  to  the  line  printer.  The 
/SP  switch  need  not  be  present  because  it  Is  the  default.  The  /-WI 
switch  specifies  an  80-column  line  printer  listing  format. 


NOTE 

For  the  command  sequence  above  to  work 
in  a  multiuser  protection  system.  It 
must  be  Input  from  a  privileged 
terminal . 


The  STACK=0  option  suppresses  the  stack  area  in  the  common's  image 
file.  The  PAR  option  specifies  that  the  device  common  will  reside 
within  a  partition  of  the  same  name  as  that  of  the  common.  As  with 
the  data  common  in  Example  5-1  (Section  5.1.7),  this  is  a  requirement 
of  the  RSX-llM  system;  in  an  RSX-llM-PLUS  system  it  is  not.  The  PAR 
option  also  specifies  that  the  base  of  the  common  is  0  and  that  it  is 
100  (octal)  bytes  long. 
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The  TKB  map  for  TTCOM  that  results  from  the  command  sequence  above  is 
shown  in  Example  5-2,  Part  2.  The  task  attributes  section  of  this  map 
indicates  that  the  common  is  position  independent  and  that  no  header 
is  associated  with  it.  The  common's  image  and  symbol  definition  file 
reside  on  device  LB:   under  UFD  (1,1). 

The  map  in  Example  5-2,  Part  2  shows  the  global  symbols  defined  in  the 
common  with  their  relative  offsets  into  the  common  region.  You 
establish  the  virtual  base  address  for  the  common  and  the  virtual 
addresses  for  the  symbols  within  it  when  you  build  the  tasks  that  link 
to  the  common. 

You  establish  the  physical  addresses  for  the  common  with  the  MCR 
command  SET.  The  keyword  that  you  use  with  the  SET  command  depends  on 
which  system  you  are  running.  If  your  system  is  an  RSX-llN  system, 
use  the  command 


>SET  /MAIN-TTCOM:7775:l:DEV 

If  your  system  is  one  that  uses  22-bit 
command 

>SET  /MA1N=TTC0M:177775:1:DEV 


physical   addresses,   use   the 


If  your  system  is  an  RSX-llM-PLUS  system,  use  the  command 

>SET  /PAR=TTCOM: 177775 :1:DEV 

These  previous  SET  command  sequences  create   a  main   partition   named 
TTCOM   that   begins   at   physical  address  777500  in  18-bit  systems  and 

physical  address  1777750  in  22-bit   systems.  The   partition   is   one 

64-byte   block   long,  (lOO(octal)  bytes).   The  argument  DEV  identifies 

the  partition  type.   With  the  common  built  and  the  partition   for   it 

created,   you  must  install  TTCOM  in  an  RSX-llM  system  before  using  it. 
For  example,  use 


>INS  LB: [1,1] TTCOM 

You  can  establish  the  partition  for  a  device  common  at  any  time  in 
both  the  RSX-llM  and  the  RSX-llM-PLUJ  systems.  Partitions  created  to 
accommodate  a  device  common  are  not  a  system  generation  consideration 
because  they  represent  areas  of  physical  address  space  above  memory 
and  therefore  cannot  conflict  with  memory  partitions. 


Example  5-2,  Part  2   Task  Builder  Map  for  TTCOM 


TTCOM. TSK;1    Memory  allocation  m.Tp   TKB  M40.10       Page  1 

l-DEC-82    1 , :02 


Partition  name  :  TTCOM 

Ident  i  f  icat  ion  : 

Task   UIC       :  [7,62] 

Task  attributes:  -HD,PI 

Total  address  windows:  1. 

Task   image   size   :  32.  WORDS 


TASK 

ATTRIBUTES 

SECTION 


(continued  on  next  page) 
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Example  5-2,  Part  2  (Cont.)   Task  Builder  Map  for  TTCOM 


Task  address  limits:  000000  000067 

R-W  disk  blk  limits:  000002  000002  000001  00001. 

**•  Root  segment:  TTCOM 


R/W  mem   limits:  000000  000067  000070  00056. 
Disk  blk  limits:  000002  000002  000001  00001. 


Memory  allocation  synopsis; 
Section 


Title   Ident   File 


.  BLK. : (RW, I ,LCL,REL,CON)  000000  000000  00000. 
TTCOM  : (RW,D,GBL,REL,OVR)  000000  000070  00056. 

000000  000070  00056.  .MAIN. 


TTCOM. OB J, '1 


Global  symbols: 

$RBUF   000062-R   $RCSR   000060-R   $XBUF   000066-R   $XCSR   000064-R 

***  Task  builder  statistics: 

Total  work  file  references:  214. 
Work   file   reads:  0. 


Work  file  writes: 
Size  of  core  pool: 
Size  of  work  file: 


0. 

6666.  WORDS  (26.  PAGES) 

768.  WORDS  (3.  PAGES) 


Elapsed  t ime  :  00 : 00 : 02 

Example  5-2,  Part  3  shows  an  assembly  listing  for  a  demonstration 
program  named  TEST.  When  built  and  installed,  TEST  will  print  the 
letters  A  through  Z  on  the  console  terminal  by  directly  accessing  the 
console  terminal  status  and  data  registers.  It  will  access  the  status 
and  data  registers  through  the  device  common  TTCOM. 


Example  5-2,  Part  3   Assembly  Listing  for  TEST 


.TITLE 

TEST 

. IDENT 

/Ol/ 

.MCALL 

EXITSS 

START:   MOV 

#15, RO 

CALL 

OUTBYT 

MOV 

#12, RO 

CALL 

OUTBYT 

MOV 

#101, RO 

MOV 

#26.,R1 

START  WITH  A  CARRIAGE  RETURN 

PRINT  IT 

THEN  A  LINE  FEED 

PRINT  IT 

FIRST  LETTER  IS  AN  "A" 

NUMBER  OF  LETTERS  TO  PRINT 


(continued  on  next  page) 
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Example  5-2,  Part  3  (Cont.)   Assembly  Listing  for  TEST 


OUTPUT: 

CALL 

OUTBYT 

;  PRINT  CURRENT  LETTER 

DEC 

Rl 

;  ONE  LESS  TIME 

BNE 

OUTPUT 

;  AGAIN 

MOV 

#15, RO 

•  ANOTHER  CARRIAGE  RETURN 

CALL 

OUTBYT 

MOV 

#12, RO 

;  ANOTHER  LINE  FEED 

CALL 

OUTBYT 

EXIT$S 

OUTBYT: 

TSTB 

$XCSR 

•  OUTPUT  BUFFER  READY? 

BPL 

OUTBYT 

IF  NOT  WAIT 

MOV 

RO,$XBUF 

;  MOVE  CHARACTER  TO  OUTPUT  BUFFER 

INC 

RO 

INITIALIZE  NEXT  LETTER 

RETURN 

.END 

START 

Once  you  have  assembled  TEST,  you  can  build  it  with  the  following  TKB 
command  sequence: 

>TKB 

TKB>TEST,TEST/-WI/MA=TEST 

TKB>/ 

Enter  Options: 

TKB>C0MMON=»TTC0M:RW:  1 

TKB>// 

The  COMMON  option  in  this  command  sequence  tails  TKB  that  TEST  intends 
to  access  the  de^'ice  common  TTCOM  and  that  TEST  will  have  read/write 
access  to  it.  It  also  directs  TKB  to  reserve  APR  1  for  mapping  the 
common  into  TEST'S  virtual  address  space. 


The  TKB  map  that  results 
Example  5-2,  Part  4. 


from  the  command  sequence  above  is   shown   in 


This  map  contains  a  global  symbols  section.  TKB  included  it  because 
the  /MA  switch  was  applied  to  the  memory  allocation  file  at  task-build 
time.  Note  that  the  global  symbols  in  this  section,  which  were 
defined  in  TTCOM,  now  have  virtual  addresses  assigned  to  them.  The 
addresses  assigned  by  TKB  are  the  result  of  the  APR  1  specification  in 
the  COMMON=  keyword  during  the  task  build. 

It  is  important  x.o  remember  that  programs  like  TEST,  which  access  the 
I/O  page,  take  complete  control  of  the  registers  they  reference. 
Therefore,  coding  errors  in  such  programs  can  disable  the  devices  they 
reference  and  can  even  make  it  impossible  for  the  device  drivers  to 
regain  control  of  the  device.  If  this  happens,  you  must  reboot  the 
system. 
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Example    5-2,    Part    4      Memory   AUrcation    Map    for    TEST 


TEST.TSK;!         Memory    allocation   map   TKB   M40.10  Page    I 

l-DEC-82    17:03 


Partition  name  :  GEN 

Identification  :  01 

Task   UIC       :  [7,62] 

Stack     limits:  000274  001273  001000  00512. 

PRG  xfr  address:  001274 

Total  address  windows:  2. 

Task   image   size   :  384.  WORDS 

Task  address  limits:  000000  001377 

R-W  disk  blk  limits:  000002  000003  000002  00002. 

***  Root  segment:  TEST 

R/W  mem   limits:  000000  001377  001400  00768. 
Disk  blk  limits:  000002  000003  000002  00002. 

Memory  allocation  synopsis: 

Section  Title   Ident   File 

.  BLK. : (RW, I ,LCL,REL,CON)  C01274  000100  00068. 

001274  000100  00068.  .MAIN.         TEST.OBJ;! 

TTCOM  : (RW,D,GBL,REL,OVR)  200000  000070  00056. 

200000  000070  00056.  TTCOM  TTCOM. STB;1 

Global  symboTs: 

$RBUF    020062-R    SRCSR    020060-R    $XBUF    020066-R    $XCSR    020064-R 

***  Task  builder  statistics: 

Total  work  file  references:  243. 

Work   file   reads:  0. 

Work   file  writes:  0. 

Size  of  core  pool:  6666.  WORDS  (26.  payes) 

Size  of  work  file:  768.  WORDS  (3.  pages) 

Elapsed  time:00 :00 :03 


5.1.11   Example  5-3:   Building  and  Linking  to  a   Resident   Library   in 
MACRO- 11 

Residorit  libraries  consist  of  subroutines  that  are  shared  by  two  or: 
more  tasks.  When  such  tasks  reside  in  physical  memory  simultaneously, 
resident  libraries  provide  a  considerable  memory  savings  because  the 
subroutines  within  the  library  appear  in  memory  only  once. 
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The  text  in  this  section  and  the  figures  associated  with  it  illustrate 
the  development  and  use  of  a  resident  library,  called  LIB. 

Example  5-3,  Part  1  shows  five  FORTRAN-callable  subroutines: 

•  An  integer  addition  routine,  AADD 

•  An  integer  subtraction  routine,  SUBB 

•  An  integer  multiplication  routine,  MULL 

•  An  integer  division  routine,  DIVV 

•  A  register  save  and  restore  coroutine,  SAVAL 

These  subroutines  are  contained  in  a  single  source  file,  LIB. MAC. 
When  assembled  and  built,  they  constitute  an  example  of  a  resident 
library.  FORTRAN-callable  routines  were  used  in  this  example  so  that 
the  routines  can  be  accessed  by  either  FORTRAN  or  MACRO-11  programs. 

Example  5-3,  Part  1   Source  Listing  for  Resident  Library  LIB. MAC 


.TITLE   LIB 
.IDENT   701/ 


•PSECT   AADD,RO,I,GBL,REL,CON 
;**  FORTRAN  CALLABLE  SUBROUTINE  TO  ADD  TWO  INTEGERS 


A/.DD : 


CALL 

$SAVAL 

SAVE  R0-R5 

MOV 

§2(R5) ,R0 

FIRST  OPERAND 

MOV 

@4(R5) ,R1 

SECOND  OPERAND 

ADD 

R0,R1             , 

SUM  THEM 

MOV 

R1,@6(R5) 

•  STORE  RESULT 

RETURN 

RESTORE  REGISTERS  AND  RETURN 

PSECT   SUBB,RO,I,GBL,REL,CON 


;**  FORTRAN  CALLABLE  SUBROUTINE  TO  SUBTRACT  TWO  INTEGERS 


SUBB; 


CALL 

$SAVAL 

MOV 

§2(R5) ,R0 

MOV 

@4(R5) ,R1 

SUB 

R1,R0 

MOV 

R0,@6(R5) 

RETURN 

SAVE  R0-R5 

FIRST  OPERAND 

SECOND  OPERAND 

SUBTRACT  SECOND  FROM  FIRST 

STORE  RESULT 

RESTORE  REGISTERS  AND  RETURN 


.PSECT   MULL,RO,I,GBL,REL,CON 

;**  FORTRAN  CALLABLE  SUBROUTilNE  TO  MULTIPLY  TWO  INTEGERS 

(continued  on  next  page) 
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Example  5-3,  Part  1  (Cont.)   Source  Listing  for  Resident  Library  LIB. MAC 


MULL: 


CALL 

$SAVAL 

SAVE  R0-R5 

MOV 

92(R5) ,R0 

•  FIRST  OPERAND 

MOV 

@4(R5) ,R1 

SECOND  OPERAND 

MUL 

R0,R1 

;  MULTIPLY 

MOV 

R1,96(R5) 

STORE  RESULT 

RETURN 

;  RESTORE  REGISTERS  AND  RETURN 

PSECT   D1VV,R0, I,GBL,REL,CON 


;**  FORTRAN  CALLABLE  SUBROUTINE  TO  DI7IDE  TWO  INTEGERS 


DTVV: 


CALL 

$SAVAL 

SAVE  REGS  RO-R"^ 

MOV 

§2(R5) ,R3 

FIRST  OPERAND 

MOV 

@4(R5),R1 

SECOND  OPERAND 

CLR 

P 

•  LOW  ORDER  16  BITS 

DiV 

R1,R2 

DIVIDE 

MOV 

P2,?6 (R5) 

STORE  RESULT 

RETURN 

RESTORE  REGISTERS  AND  RETURN 

.PSECT   SAVAL,RO,I,GBL,REL,CON 


;**ROUTINE  TO  SAVE  REGISTERS 


$SAVAL: 


MOV 

R4,-(SP) 

;SAVE  R4 

MOV 

R3,-(SP) 

SAVE  R3 

MOV 

R2,-(SP) 

SAVE  R2 

MOV 

R1,-(SP) 

SAVE  Rl 

MOV 

RO,-(SP) 

ISAVE  RO 

MOV 

12(SP)  ,-(SP) 

•COPY  RETURN 

MOV 

R5,14(SP) 

■SAVE  R5 

CALL 

@(SP)  + 

CALL  THE  CALLER 

MOV 

(SP)+,RO 

RESTORE  PO 

MOV 

(SP)+,R1 

RESTORE  Rl 

MOV 

(SP)+,R2 

RESTORE  R2 

MOV 

(SP)+,R3 

RESTORE  R3 

MOV 

(SP)+,R4 

RESTORE  R4 

MOV 

(SP)+,R5 

RESTORE  R5 

RETURN 

.END 

Once  you  have  assembled  LIB,  you  can  build  it  with  the   following   TKB 
command  sequence: 

TKB>LIB/PI/-HD/LI , LI B/-WI , L I B=LI B 

TKB>/ 

Enter  Options: 

TKB>STACK=0 

TKB>PAR=LIB:0:200 

TKB>// 
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This  command  sequence  Instructs  TKB  to  build  a  posi t ion- independent 
(/PI),  headcrless  (/-HO)  library  image  named  LIB.TSK.  It  instructs 
TKB  to  create  a  map  file  LIB. MAP  and  to  output  an  80-column  listing 
(/-WI)  to  the  line  printer.  It  also  specifies  that  TKB  Is  to  create  a 
symbol  definition  file,  LIB. STB.  TKB  creates  all  three 
files  —  LIB.TSK,  LIB. MAP,  and  LIB. STB  —  on  device  SY :  under  the  UFD 
that  corresponds  to  the  terminal  UIC.  The  /LI  and  /PI  switches  used 
together  cause  TKB  to  name  the  program  section  LIB,  which  is  the  root 
segment  of  the  library.  LIB  becomes  the  only  named  program  section  in 
the  library. 

If  you  used  the  command  sequence  above  without  the  /LI  switch,  TKB 
would  create  a  common  by  default. 

The  STACK=0  option  suppresses  the  stack  area  within  the  resident 
library's  Image.  The  PAR  option  tells  TKB  that  the  resident  library 
will  reside  within  a  partition  of  the  same  name  as  that  of  the 
library.  As  with  all  shared  regions,  this  is  a  requirement  in  an 
RSX-llM  system;  in  an  RSX-llN-PLUS  systMl  it  Is  not.  in  addition, 
the  PAR  option  specifies  that  the  base  of  the  library  Is  0  and  that  it 
is  201)  (octal)  bytes  long.  (For  more  Information  on  the  switches  and 
options  used  in  this  example,  refer  to  Chapters  10  and  11.) 

Example  5-3,  Part  2  shows  the  TKB  map  that  results  from  the  command 
sequence  above. 

Note  in  the  global  symbols  section  of  the  map  ir  Example  5-3,  Part  2 
that  TKB  has  assigned  offsets  to  the  symbols  for  each  library 
function.  When  the  task  that  links  to  this  library  is  built,  TKB  will 
assign  virtual  addresses  to  these  symbols. 

The  program  MAIN  In  Example  5-3,  Part  3  exercises  the  routines  in  the 
resident  library  LIB.TSK.  When  you  assemble  and  build  It,  MAIN  will 
call  upon  the  library  routines  to  add,  subtract,  multiply,  and  divide 
the  integers  contained  in  the  labels  OPl  and  0P2  within  the  program. 
MAIN  will  print  the  results  of  each  operation  to  device  TI : . 

Example  5-3,  Part  2   Task  Builder  Map  for  LIB.TSK 

LIB.TSK;1       Memory  allocation  map   TKB  M40.10      Page  1 

ll-DEC-82    13:50 


Partition  name  :  LIB 

Identification  :  01 

Task   UIC       :  [7,62] 

Task  Attributes:  -HD,PI 

Total  address  windows:  1. 

Task   image   size   :  64.  WORDS 

Task  address  limits:  000000  000163 

R-W  disk  blk  limits:  000002  000002  000001  00001 

***  Root  segment:  LIB 


R/W  mem   limits:  000000  000163  000164  00116, 
Disk  blk  limits:  000002  000002  000001  00001, 


(continued  on  next  page) 
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Example  5-3,  Part  2  (Cont.)   Task  Builder  Map  fcr  LIB.TSK 


Memory  allocation  synopsis; 
Sect  ion 


Title   Ident   File 


.  BLK. : (RW, I,LCL,REL,CON)  000000 
AADD   : (RO, I,GBL,REL,CON)  000000 

000000 
DIVV   : (RO, I,GBL,REL,CON)  000024 

000024 
MULL   : (RO, I,GBL,REL,CON)  000052 

000052 
SAVAL  : (RO, I,GBL,REL,CON)  000076 

000076 
SUBB   :  (RO,  I,GBL,REL,CO:.-)  000140 

000140 


000000 

00000. 

000024 

00020. 

000024 

00020. 

LIB 

01 

LIB 

OBJ;  2 

000026 

00022. 

000026 

00022. 

LIB 

01 

LIB 

.OBJ; 2 

000024 

00020. 

000024 

00020. 

LIB 

01 

LIB 

OBJ ;  2 

000042 

00034. 

000042 

00034. 

LIB 

01 

LIB 

OBJ;  2 

000024 

00020. 

000024 

00020. 

LIB 

01 

LIB 

OBJ;  2 

Global  symbols; 


AADD 
DIVV 


000000-R 
000024-R 


MULL 


000052-R  SUBB 


000140-R 


***  Task  builder  statistics: 

Total  work  file  references:  368. 

Work   file   reads:  0. 

Work   file  writes:  0. 

Size  of  core  pool:  7086.  WORDS  (27.  PAGES) 

Size  of  work  file:  768.  WORDS  (3.  PAGES) 

Elapsed  time:00:00 :03 


Example  5-3,  Part  3   Source  Listing  for  MAIN. MAC 


;  + 

;**MAIN 


•TITLE   MAIN 
.IDENT   /Ol/ 


CALLING  ROUTINE  TO  EXERCISE  THE  ARITHMETIC  ROUTINES 
FOUND  IN  THE  RESIDENT  LIBRARY,  LIB.TSK. 


.MCALL 

QIO 

OPl: 
0P2: 
ANS: 
OUT: 

.WORD 
.WORD 
.BLKW 
.BLKW 

1 
1 
1 
100 

QIOW$S,EXIT$S 


OPERAND  1 
OPERAND  2 
RESULT 
FORMAT  MESSAGE 


(continued  on  next  page) 
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Example  5-3,  Part  3  (Cont.)   Source  Listing  for  MAIN. MAC 


FORMAT:  .ASCIZ 

/THF,  ANSWER 

.EVEN 

.ENABL 

CT  &  DT  • 

LSB 

b 1 AK 1 : 

MOV 

#ANS,-(SP) 

MOV 

#0P2,-{SP) 

MOV 

#0P1,-(SP) 

MOV 

#3,-(SP) 

MOV 

SP,R5 

CALL 

AADD 

CALL 

PRINT 

MOV 

SP,R? 

CALL 

SUBB 

CALL 

PRINT 

MOV 

SP,R5 

CALL 

MULL 

CALL 

PRINT 

MOV 

SP,RS 

CALL 

DIVV 

CALL 

PRINT 

EXIT$S 

%D./ 


TO  CONTAIN  RESULT 

OPERAND  2 

OPERAND  1 

PASSING  3  ARGUMENTS 

ADDRESS  OF  ARGUMENT  BLOCK 

ADD  TWO  OPERANDS 

PRINT  RESULTS 

ADDRESS  OF  ARGUMENT  BLOCK 

SUBTRACT  SUBROUTINE 

PRINT  RESULTS 

ADDRESS  OF  ARGUMENT  BLOCK 

MULTIPLY  SUBROUTINE 

PRINT  RESULTS 

ADDRESS  OF  ARGUMENT  BLOCK 

DIVIDE  SUBROUTINE 

PRINT  RESULTS 


;**  PRINT  -  PRINT  RESULT  OF  OPERATION, 


PRINT: 


MOV 

MOV 

MOV 

CALL 

QIOW$S 

RETURN 

.END 


#OUT,R0 
#FORMAT,RL 
«ANS,R2 
$EDMSG 


ADDRESS  OF  SCRATCH  AREA 
FORMAT  SPECIFICATION 
ARGUMENT  TO  CONVERT 
FORMAT  MESSAGE 


#I0.WVB,»5,#1,  ,,  ,<#OUT,R1,HO> 

;  RETURN  FROM  SUBROUTINE 
START 


Once  you  have  assembled  MAIN,  you  can  use  the  following  TKB  command 
sequence  to  build  it: 

TKB>MAIN,MAIN/MA/-WI/-SP=MAIN 

TKB>/ 

Enter  Options: 

TKB>RESLIB=LIB/R0:3 

TKB>// 

This  command  sequence   instructs   TKB   to   build   a   task  file   named 

MAIN.TSK  on  device  SY:  under  the  UFD  that  corresponds  to  the  terminal 
UIC.   It  also  specifies  that  TKB  is  to  create   a   map   file   MAIN. MAP. 

The   /MA  switch  requests  an  extended  map  format.   In  this  example,  /MA 

was  applied  to  the  device  specification  so  that  TKB  would  include   in 

the   map  for  the  task  the  symbols  within  the  library  LIB.  The  negated 

form  of  the  wide   listing   switch   (/-WI)   was   appended  to   the   map 

specification  to  obtain  an  80-column  map  format.  In  this  example,  TKB 
will  not  output  a  map  listing  to  the  line  printer 

The  RBSLIB  option  specifies  that  the  task  MAIN  is  to  access  the 
library  LIB  and  that  it  requires  read-only  access  to  LIB.  TKB  uses 
APR3  to  map  the  library. 


The  TKB  map  that  results   from   this 
Example  5-3,  Part  4. 


command   sequence   is   shown   in 
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Example  5-3,  Part  4   Task  Builder  Map  for  MAIN.TSK 


MA  I N . TS  K ; 1 


Memory  allocation  map  TKB  M40.10 
ll-DEC-82    13:51 


Page  1 


Partition  name  :  GEN 

Ident  i  t icat  ion  :  01 

Task   UIC       :  |7,62| 

Stack     limits:  000274  001273  001000  00512. 

PRG  xfr  address:  001634 

Total  address  windows:  2. 

Task   image   size   :  1152.  WORDS 

Task  address  limits:  000000  004327 

R-W  disk  blk  limits:  000002  000006  000005  00005, 

•**  Root  segment:  MAIN 


R/W  mem   limits : 
Disk  blk  limits: 


000000  004327  004330  02264. 
000002  000006  000005  00005. 


Memory  allocation  synopsis: 


Sect  ion 


Title   Ident   File 


BLK.  :  (RW, I ,LCL,REL,CON) 


AADD 


DIVV 


MULL 


SAVAL 


SUBB 


SSRESL 


(RO, I,GBL,REL,CON) 
(RO, I ,GBL,REL,CON) 
(RO, I ,GBL,REL,CON) 
(RO,I ,GBL,REL,CON) 
(RO, I ,GBL,REL,CON) 
(RO, I ,LCL,REL,CON) 


001274 

002620 

01424. 

001274 

000530 

00344. 

MAIN 

01 

002024 

001050 

00552. 

EDTMG 

15 

003074 

000216 

00142. 

CBTA 

04 

003312 

000074 

00060. 

CATB 

03 

003406 

000250 

00168. 

EDDAT 

03 

003656 

000126 

00086. 

CDDMG 

00 

004004 

000110 

00072. 

C5TA 

02 

060000 

000024 

00020. 

060000 

000024 

0002-^. 

LIB 

01 

060024 

000026 

00022. 

060024 

000026 

00022. 

LIB 

01 

060052 

000024 

00020. 

060052 

000024 

00020. 

LIB 

01 

060076 

000042 

Ono34. 

060076 

000042 

.  34. 

LIB 

01 

060140 

000024 

o0020. 

060140 

000024 

00020. 

LIB 

01 

004114 

000212 

00138. 

004114 

000024 

00020. 

SAVRG 

04 

004140 

000066 

00054. 

ARITH 

03 

004226 

000100 

00064. 

DARITH 

00 

MA  I  N.OB J; 1 
SYSLIB.OLB; 1034 
SYSLIB.OLB; 1034 
SYSLIB.OLB; 1034 
SYSLIB.OLB;1034 
SYSLIB.OLB; 1034 
SYSLIB.OLB; 1034 

LIB.STB;17 

LIB.STB;17 

LIB. STB; 17 

LIB. STB; 17 

LIB. STB; 17 

SYSLIB.OLB;1034 


(continued  on  next  page) 
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Example  5-3,  Part  4  (Cont.)   Task  Builder  Map  for  MAIN.TSK 


Global  symbols: 


AADD 

060000-R 

$CBOSG 

003110-R 

SCDTB 

003312-R 

SEDMSG 

002122- 

■R 

DIVV 

060024-R 

SCHOMG 

001116-R 

SCOTB 

003320-R 

SMUL 

004 140- 

-R 

lO.WVB 

01 1000 

SCBOSG 

003124-R 

SC5TA 

004004-R 

SSAVRG 

0041  14- 

R 

MOLL 

060052-R 

SCBTA 

003154-R 

$DAT 

003452-H 

STIM 

003532- 

R 

SUBB 

060140-R 

SCBTMG 

003132-R 

SDDIV 

004264-R 

SCBDAT 

00J074-R 

$CBVER 

003118-R 

SDIV 

004170-R 

SCBUMG 

003102-R 

SCDDMG 

003656-R 

SDMUL 

004226-R 

Task  builder  statijticsi 

Total  work  file  references:  2218. 
Work   file   reads:  0. 

Work   file  writes:  0. 

Size  of  core  pool:  2066.  words  (8. 
Size  of  work  file:  1024.  words  (4. 

pages 
pages 

Elapsed  t ime : 00 : 00  :  19 


This  map  contains  a  globl  symbols  section.  Note  that  the  symbols 
within  the  library  now  have  virtual  addresses  assigned  to  them  and 
that  these  addresses  begin  at  60000 (octal )  ,  the  virtual  base  address 
of  APR  3.  The  Task  Builder's  allocation  of  virtual  address  space  for 
MAIN.TSK  is  represented  diagrammat icall y  in  Figure  5-9. 


APR  7  — 


APRS- 


APR  5  — 


APR  4  — 


VIRTUAL  60000  APR  3— 


APR  2— 


APR  1  — 

VIRTUAL  0    APRO  — 


UNUSED 


LIB.  TSK 


UNUSED [ 


MAIN.  TSK 


^  WINDOW  1    REGION  1 


} 


WINDOW  0   REGION  0 


Figure    5-9      Allocation   of    Virtual    Addresb   Space    for    MAIN.TSK 
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The  library  LIB  is  position  independent  and  can  therefore  be  mapped 
anywhere  in  the  referencing  task's  virtual  address  space.  APR  3  was 
UHed  in  this  example  to  contrast  this  mapping  arrangement  with  the 
mapping  of  MACCOM  in  the  virtual  address  space  of  task  MCOMl  in 
Example  5-1  (Section  5.1.7).  If  the  optional  APR  parameter  in  the 
RESLIB  option  above  had  been  left  blank,  TKB  would  have  allocated  the 
highest  available  APR  to  map  the  library. 


5.1.11.1   Resolving   Program   Section   Names  in  a   Shared   Region  -  As 

described  in  earlier  sections  of  this  chapter,  program  section  names 
within  position-independent  shared  regions  must  normally  be  unique 
with  respect  to  program  section  names  within  tasks  that  reference 
them.  When  a  shared  region  is  a  position-independent  resident  common 
and  you  explicitly  declare  the  program  section  names  within  it, 
avoiding  program  section  name  conflicts  is  an  easy  matter.  However, 
when  a  shared  region  is  a  position-independent  resident  library  that 
contains  calls  to  routines  within  an  object  module  library  (SYSLIB, 
for  example),  conflicts  may  develop  that  are  not  apparent  to  you.  The 
problem  arises  when  the  position-independent  resident  library  and  one 
or  more  tasks  that  link  to  it  contain  calls  to  separate  routines 
residing  within  the  same  program  section  of  an  object  module  library. 

When  TKB  resolves  a  call  from  within  a  module  that  it  is  processing  to 
a  routine  within  an  object  module  library,  it  places  the  routine  from 
the  library  into  the  image  it  is  building.  It  also  enters  into  its 
internal  table  the  name  of  the  program  section  in  the  object  module 
library  within  which  the  routine  resides.  If  a  position-independent 
resident  library  contains  a  call  to  a  routine  within  a  given  program 
section  of  SYSLIB,  for  example,  and  then  subsequently  a  task  that 
links  to  the  resident  library  contains  a  call  to  a  different  routine 
within  the  same  program  section  of  SYSLIB,  both  the  resident  library 
and  the  referencing  task  will  contain  the  program  section  name.  When 
you  build  the  referencing  task,  the  library's  .STB  file  will  contain 
the  program  section  name  and  a  program  section  conflict  will  develop. 
(Refer  to  Section  5.1.5  for  additional  information  on  the  sequence  in 
which  TKB  processes  tasks  and  the  potential  program  section  name 
conflicts  that  can  result.) 

This  situation  and  one  possible  solution  to  it  can  be  illustrated  with 
Example  5-3.  When  this  example  was  first  created,  only  the  arithmetic 
routines  were  included  in  the  source  file  of  the  resident  library 
(LIB. MAC  in  Example  5-3,  Part  1).  The  system  library  coroutine 
($SAVAL)  was  resolved  from  SYSLIB.  Because  the  first  instruction  of 
each  arithmetic  routine  called  $SAVAL,  TKB  included  a  copy  of  it  in 
the  resident  library's  image  at  task-build  time.  This  turned  out  to 
be  unsatisfactory  because  of  a  call  to  the  SYSLIB  routine  $EDMSG  (edit 
message)  within  the  program  MAIN  that  links  to  the  resident  library. 
Both  routines  ($SAVAL  and  $EDMSG)  reside  within  the  unnamed  or  blank 
program  section  (.  BLK.)  within  SYSLIB.  Therefore,  a  program  section 
name  conflict  developed  when  MAIN  was  built. 

To  circumvent  this  problem,  the  source  code  for  $SAVAL  was  included  in 
the  source  file  for  the  resident  library  under  the  explicitly  declared 
program  section  name  SAVAL. 

Another  solution  would  have  been  to  build  the  resident  library 
absolute.  In  this  case,  TKB  would  not  have  included  program  section 
names  from  the  resident  library  into  the  .STB  file  for  the  resident 
library. 
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It  is  important  to  note  that  the  above  proijram  section  name  conflict 
develops  only  when  two  different  routines  residing  within  the  same 
program  section  of  an  object  module  library  are  involved.  It  presents 
no  problem  when  a  resident  library  and  a  task  that  links  to  it  contain 
a  call  to  the  same  routine  in  an  object  module  library.  In  that  case, 
TKB  copies  the  routine  and  the  program  section  name  in  which  It 
resides  into  the  resident  library  when  the  library  is  built.  Then, 
when  the  task  that  calls  the  same  routine  is  built,  TKB  resolves  the 
reference  to  the  routine  in  the  resident  library  instead  of  in  the 
object  module  library. 


5.1.12   Example  5-4:   Building  a  Task  That  Creates  a  Dynamic  Region 

In  all  the  examples  of  tasks  shown  thus  far  in  this  chapter,  TKB  has 
automatically  constructed  and  placed  in  the  header  of  the  task  all  of 
the  window  blocks  necessary  to  map  all  of  the  regions  of  the  task's 
image.  The  INSTALL  processor  has  been  responsible  for  initializing 
the  window  blocks  when  the  task  was  installed.  In  all  the  examples, 
this  has  been  possible  because  both  TKB  and  the  INSTALL  processor  have 
had  all  the  information  concerning  the  regions  available  to  them. 

When  a  task  creates  regions  while  it  is  running  (dynamic  regions),  the 
information  concerning  the  regions  is  not  available  to  either  the  Task 
Builder  or  INSTALL.  Therefore,  when  TKB  builds  such  a  task,  it  does 
not  automatically  create  window  blocks  for  the  dynamic  regions.  It 
creates  only  the  window  blocks  necessary  to  map  the  task  region  (the 
region  containing  the  header  and  stack)  and  any  shared  regions  that 
the  task  references. 

Dynamic  regions  are  created  and  mapped  with  Executive  directives  that 
are  imbedded  in  the  task's  code.  When  you  build  a  task  that  creates 
dynamic  regions,  you  must  explicitly  specify  to  TKB  how  many  window 
blocks  (in  excess  of  those  created  by  TKB  for  the  task  region  and  any 
shared  regions)  it  is  to  place  in  the  task's  header.  Tlie  Executive 
will  initialize  these  window  blocks  when  it  processes  the  region  and 
mapping  directives.  In  all  (including  window  blocks  for  the  task 
region  and  shared  regions),  you  can  include  as  many  as  8  window  blocks 
to  a  task  in  an  RSX-llM  system  and  as  many  as  16  in  an  RSX-llM-PLUS 
system. 

The  text  in  the  remainder  of  this  section  and  the  figures  associated 
with  it  illustrate  the  development  of  a  task  that  creates  dynamic 
regions.  Example  5-4  shows  a  task  (DYNAMIC.MAC)  that  creates  a  128- 
word  dynamic  region.  This  task  simply  creates  an  unnamed  region,  maps 
to  it,  and  fills  it  with  an  ascending  sequence  of  numbers  beginning  at 
the  region's  base  and  moving  upwards.  When  the  region  is  full, 
DYNAMIC  detaches  from  it  and  prints  the  following  message  on  your 
terminal: 

DYNAMIC  IS  NOW  EXITING 

The  region  is  automatically  deleted  on  detach. 

All  of  the  Executive  directives  used  by  DYNAMIC  (RDBBK$,  WDBBK$, 
DTRG$S,  EXIT$S,  CRRG$S,  CRAW$S,  QIOW$S,  and  QIOW$C)  to  create  and 
manipulate  the  region  are  described  in  the  RSX-llM/M-PLUS  Executive 
Reference  Manual .  These  directives  are  SYSGEN  options  on  RSX-llM 
systems. 
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Example  5-4,  Part  1   Source  Listing  for  DYNAMIC. MAC 


RDB: 


.TITLE  DYNAMIC 

.IDENT  /vol/ 

.MCALL  RDBBK$,WDBBK$,DTRG$S,EXIT$S,CRRG$S,CRAW$S 

.MCALL  QIOW$C,QIOW$S 

.NLIST  BEX 

REGION  DESCRIPTOR  BLOCK 

WORD  0  SIZE  OF  REGION  IN  32  DECIMAL  WORD  BLOCKS 

WORD  1  REGION  NAME 

WORD  2       "" 

WORD  3  NAME  OF  SYSTEM  CONTROLLED  PARTITION  IN 

WORD  4  WHICH  REGION  WILL  BE  CREATED 

WORD  5  STATUS  WORD 

WORD  6  PROTECTION  WORD 

RDBBK$  128. , , GEN , < RS . MDL 1 RS . ATT ! RS . DEL  I RS . RED ! RS . WRT> , 1700 17 

WINDOW  DESCRIPTOR  BLOCK 

WORD  0  APR  TO  BE  USED  TO  MAP  REGION 

WORD  1  SIZE  OF  WINDOW  IN  32-WORD  BLOCKS 

WORD  2  REGION  ID 

WORD  3  OFFSET  INTO  REGION  TO  START  MAPPING 

WORD  4  LENGTH  IN  32-WORD  BLOCKS  TO  MAP 

WORD  5  STATUS  WORD 


WDB: 
MESl: 

ERRl: 

ERR2: 

ERR3: 


START! 


20$: 


WDBBK$ 
•ASCIZ 
SI  =  . 
.ASCII 
SIZl  = 
.ASCII 
SIZ2  = 
•ASCII 
SIZ3  = 
.EVEN 
.PAGE 
.ENABL 

CRRG$S 

BCS 

MOV 

CRAW$S 

BCS 

MOV 

MOV 

.REPT 

ASL 

.ENDR 

MOV 

MOV 

INC 

DEC 

BGT 

DTRG$S 

BCS 

QIOW$C 

EXIT$S 


7,12  8. ,0,0, ,WS.MAP!WS.WRT> 

/DYNAMIC  IS  NOW  EXITING/ 
-  MESl 

/CREATE  REGION  FAILED/ 
.  -  ERRl 

/CREATE 
,  -  ERR2 

.    -    ERR3 


ADDRESS  WINDOW  FAILED/ 
REGION  FAILED/ 


LSB 

#RDB 

1$ 

RDB+R. 

#WDB 

2$ 

WDB+W. 

WDB+W. 

5 

R2 

#1,R1 

Rl, (RO 

Rl 

R2 

20$ 

#RDB 

3$ 

lO.WVB 


REGION 


RO 
R2 


;  CREATE  A  128  WORD  UNNAMED 

;  FAILED  TO  CREATE  REGION 
GID, WDB+W. NRID  ;  COPY  REGION  ID  INTO  WINDOW  BLOCK 

;  CREATE  ADDR  WINDOW  AND  MAP 

;  FAILED  TO  CREATE  ADDR  WINDOW 

;  BASE  ADDR  OF  CREATED  REGION 

;  NUMBER  OF  32.  WORDS  IN  REGION 

;  MULTIPLY 

;  BY 

;  32. 

;  INITIAL  VALUE  TO  PLACE 

;  MOVE  VALUE  INTO  REGION 

;  NEXT  VALUE  TO  PLACE  IN 

;  ONE  LESS  WORD  LEFT 

;  TO  FILL  IN 

;  DETACH  AND  DELETE  REGION 

;  DETACH  FAILED 
,  ,<MES1,S1,40> 


NBAS, 
NSIZ, 


)  + 


IN  REGION 


REGION 


5,1, 


(continued  on  next  page) 
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Example  5-4,  Part  I  (Cont.)   Source  Listing  for  DYNAMIC.MAC 


I 

1$: 


2$; 

3$; 
6$; 


ERROR  ROUTINES 


MOV 

»ERR1,R0 

MOV 

»SIZ1,R1 

BR 

6$ 

MOV 

#ERR2,R0 

MOV 

*SIZ2,R1 

BR 

6$ 

MOV 

»ERR3,R0 

MOV 

#SIZ1,RI 

QIOW$S 

#I0.WVB,#5 

EXIT$S 

.END 

START 

l»l 


;  CREATE  FAILED 

;  SIZE  OF  MESSAGE 

;  WRITE  MESSAGE 

;  CREATE  ADDRESS  WINDOW 

;  SIZE  OF  MESSAGE 

;  DETACH  FAILKD 

;  SIZE  OF  MESSAGE 
,<RO,R1,»40> 


FAILED 


Once  you  have  assembled 
TKB  command  sequence: 


DYNAMIC,  you  can  build  it  with   the   following 


TKB>DYNAMIC,DYNAMIC/-W I /-SP= DYNAMIC 

TKB  •  / 

Enter  Options: 

TKB>WNDWS=1 

TKB>// 

This  command  sequence  directs  TKB  to  create  a  task  image  named 
DYNAMIC. TSK  and  an  80-column  (/-WI)  map  file  named  DYNAMIC. MAP  on 
device  SY:  under  the  terminal  UIC.  Because  /-SP  is  attached  to  the 
map  file,  TKB  does  not  output  the  file  to  the  line  printer. 

Under  options,  the  WNDWS  option  directs  TKB  to  create  one  window  block 
over  and  above  that  required  to  map  the  task  region.  Note  that  one 
window  block  must  be  created  for  each  region  the  task  expects  to  be 
mapped  to  sijnul taneousl y . 

The  map  that  results  from  this  command  sequence  is  shown  in  Example 
5-4,  Part  2. 

Note  that  creating  dynamic  regions  always  involves  the  assumption  that 
there  will  be  enough  room  in  the  partition  named  in  the  task's  region 
descriptor  block  to  create  the  region  when  the  task  is  run.  In  this 
example,  if  DYNAMIC  were  to  be  run  in  a  system  whose  partition  GEN  was 
not  large  enough  to  accommodate  the  r«3ion  it  creates,  the  CREATE 
REGION  directive  would  fail. 
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Example    5-4,    Part    2      Task    Builder    Map    for    DYNAMIC. TSK 


DYNAMIC.TSK;i      Memory   allocation   map      TKB   M40.10  Page    I 

ll-DEC-82      16:05 


Partition  nnme  :  GEN 

Identification  :  VOl 

Task   UIC       :  |7,62) 

Stack  limits:    000274    001273    OOIOOO    00512. 

PRO   xfr    address:    001470 

Total    address    windows:    2. 

Task       image      size      :    512.    WORDS 

Task    address    limits:    000000    001753 

R-W  disk    blk    limits:    000002    000003    000002    00002. 

***    Root    segment:    DYNAMI 

R/W  mem      limits:    000000    001753    001754    01004. 
Disk    blk    limits:    000002    000003    000002    00002. 

Memory   allocation   synopsis: 

Section  Title      Ident      File 


.    BLK. : (RW, I ,LCL,REL,CON)     001274  000430  00280. 

001274  000430  00280.  DYNAMI    VOl  DYNAMIC . OBJ ; 1 

SDPB$$: (RW, I,LCL,REL,CCN)     001724  000030  00024. 

001724  000030  00024.  DYNAMI    VOl  DYNAMIC. OBJ; 1 


Task 

bu  1 

Ider 

Stat  i  st  ics 

Total 

work  f 

i  le  re 

ferences: 

549. 

Work 

f  1 

le 

reads: 

0. 

Work 

f  i 

le  writes: 

0. 

Size 

of 

coia 

pool  : 

7086 

wor 

ds  (27. 

pages) 

Si  ze 

of 

work 

file: 

763. 

word 

s  n.  p 

ages) 

Elapsed    t ime  :  00 : 00 : 06 


5.2      CLUSTER    LIBRARIES 


The  term  "cluster  libraries"  refers  to  both  a  function  and  a  structure 
created  by  the  Task  Builder  (TKB)  that  allow  a  task  to  dynamically  map 
memory-resident  shared  regions  at  run  time.  Cluster  libraries  permit 
a  task  to  use,  for  example,  a  F77CLS  library,  an  FMS-11  library,  and 
an  FCS-11  library,  all  mapped  through  the  same  task  address  window. 
The  run-time  routines  put  into  the  task  by  the  Task  Builder  remap  the 
library  regions  so  that,  instead  of  occupying  48K  bytes  of  virtual 
address   space,    they    share    16K   bytes    of    virtual    address    space. 

One  task  address  window  (window  1)  maps  the  libraries  into  the  same 
span  of  virtual  address  space  (48Kb  to  64Kb).  TKB  maps  your  task  from 
virtual    0    upward. 


» 
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TKB  implements  the  cluster  library  function  in  two  parts.  The  first 
part,  revectoring  of  interlibrary  calls,  is  independent  of  the  actual 
remap  mechanism  but  is  required  for  remapping  to  work.  The  second 
part  executes  the  required  MAP$  directives  to  map  the  appropriate 
1 ibrar y . 

The  following  examples  use  the  library  and  task  structure  shown  in 
Figure  5-10.  Note  that  in  the  following  examples,  the  FMS-11/RSX  VI. 0 
and  FORTRAN-77  software  products  are  sold  under  separate  license  and 
are  not  included  with  the  RSX-llM  or  RSX-llM-PLUS  system.  Cluster 
library  support  may  be  used  with  RMS-11  V2 . 0  or  later  versions,  and 
operates  in  a  fashion  similar  to  the  FCS-11  example.  Also,  the 
particular  FCSRES  used  below  is  generated  by  SYSGEN.  It  consists  of 
two  PLAS  overlays  and  a  null  root. 


FORTRAN  OTS  LIBRARY 
F77CLS 

FMS-11  LIBRARY 
FMSCLS 

FCS-11  LIBRARY 
FCSRES 

USER 
TASK 

VIRTUAL 
ADDRESS 

64KB 


4eKB 


Figure  5-10   Example  Library  and  Task  Structure 


5.2.1   Building  the  Libraries 

You  must  follow  several  rules  when  designing  and  building  shareable 
clustered  libraries.  The  rules  are  summarized  next  and  discussed  in 
detail  following  the  summary. 


5.2.1.1   Summary  of  Rules  for  Building  the  Libraries  - 

All  libraries  but  the  first  require  resident  overlays. 

User   task   vectors   indirectly    resolve    all    interlibrary 
references . 


Revectored   entry   point   symbols   must   not   appear   in 
"upstream"  .STB  file. 


the 


A  called  library  procedure  must  not  require  parameters  on   the 
stack . 

All  the  libraries  must  be  PIC  or  built  for  the  same  address. 

Trap  or  asynchronous  entry  into  a  library  is  not  permitted. 

The  rules  are  discussed  in  detail  as  follows. 
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S.2.1.2  Rule  1:  All  Libraries  but  fche  Pirsfc  Requi 
Overlays  -  The  first  library  is  the  first  nam 
the  CLSTR  option  line.  To  obtain  the  required  run-timo 
structures  in  your  task,  you  must  define  all  the  lib 
possibly  the  first  by  using  memory  resident  overlays.  Al 
be  an  overlaid  library,  the  f  rst  library  need  not  be 
single-segment  structure.  All  the  libraries,  except  the 
have  a  null  root  if  overlaid.  You  can  achieve  this  in 
libr'^ry  is  not  normally  overlaid  by  creating  an  unbala 
structure  with  a  null  module.  For  example,  the  f 
specification  for  FMSCLS  and  a  null  module  would  suffice: 


re    Res 

ed  libra 
over  lay 
rar  ies  e 
though  i 
and  can 
f  i  rst , 
cases  wh 
need  ov 
ol lowing 


ident 

ry  in 

data 

xcept 

t  can 

be  a 

must 

ere  a 

er  lay 

ODL 


NULL: 
FMSLIB; 


.NAME 
,  ROOT 
,  FCTR 
.FCTR 
,  END 


FMSCLS 

FMSCLS-* (NULL, FMSLIB) 

LB:  [  1,1]  SYSI,  IB/LB:  NULL 

SY:FMSLIB-LB: [ 1 , I ) FDVL I B/LB 


;NULL  MODULE 
;FMS-11  ROUTINES 


The  above  ODL  specification  creates 
shown  in  Figure  5-11: 


an  unbalanced   tree   in   the   form 


;«  4J7.81 

Figure  5-11   Example  of  an  Unbalanced  Tree  with  Null  Segment 

The  effect,  after  you  build  your  task,  is  an  overlay  structure  that  is 
represented  in  the  Fir-ure  5-12. 

TKB  provides  the  cross- 1 ibrary  linkage  that  it  creates  from  the 
overlay  segment  data  contained  in  the  individual  .STB  files  of  each 
1 ibrary. 


FORTRAN  OTS 

FMS-11  ROUTINES 

FCS-11  ROUTINES 

NULL 

NULL 

USER  TASK 

Figure  5-12   Example  of  ..  n  Overlay  Cluster  Library  Structure 


5-4! 


SHARED  REGION  CONCEPTS  AND  EXAMPLES 


5.2.1.''   Rule   2:   User    Task 

Interlibrary   References 

2  and  is  a  part  of  the  example  in 
FORTRAN  OTS  library  references 
transfer  of  control  from  the  FORT 
must  be  resolved  by  a  jump  vec 
another  way,  the  CALL  instruction 
reference  directly  the  target 
FCS-11  library.  The  system  libra 
the  indirect  transfer  for  FCS-1 
you  want  to  duplicate  the  indirec 
purposes,  Figure  5-13  and  the  fol 
for  FCS-11. 


Vectors    Indirectly    Resolve   all 

-  Figure  b-13  below  illustrates  rile 

Figure  5-12.   In  Figure  5-13,  if  the 

an   FCS-11   entry   point  .OPEN,  the 

RAN  OTS  library  to  the  FCS-11  library 

tor  in  your  task.   Or,  to  state  it  in 

in  the  FORTRAN  OTS  library  must   not 

address  (the  address  of  .OPEN)  in  the 

ry  contains  the  modules  that   perform 

1  based  libraries  and  user  tasks.   If 

t  referencing  mechanism  for  your   own 

lowing  text  describe  the  control  flow 


FORTRAN  OTS 


FCS-11  LIBRARY 


FCSVEC 

OPEN:: 

Sample  code  from  FCSVEC  module: 
.OPEN::      MOV  #30,-(SP) 


BR 


DISPAT 


STACK  OFFSET  INTO  USER  TASK 

JUMP  TABLE 

JOIN  COMMON  DISPATCH 


DISPA' 


MOV 

RO,-(SP) 

MOV 

@#.FSRPT,RO 

ADD 

A.JUMP(R0),2(SP) 

MOV 

(SP).,RO 

MOV 

@(SP)..-(SP) 

RETURN 

SAVE  REGISTER 

GET  FCS-11  POINTER 

ADD  VECTOR  BASE  TO  OFFSET 

RESTORE  REGISTER 

PICK  UP  ADDRESS  OF  TARGET 

AND  TRANSFER  TO  TARGET 


ZK-429-81 


Figure  5-13   Example  of  a  Vectored  Call  Between  Libraries 


In  this  example,  the  module  FCSVEC  defines  the  .OPEN  entry  point.  The 
code  at  that  location  stacks  an  offset  or  "entry  number"  and  joins 
common  dispatch  code.  The  dispatch  code,  using  the  low  core  FCS-11 
impure  pointer  called  .FSRPT,  obtains  the  address  of  the  FCS-11  impure 
data  area.  At  offset  A. JUMP  in  that  area  is  the  address  of  a  vector 
of  FCS-11  entry  points.  A  return  is  executed,  which  transfers  control 
to  the  routine  whose  address  is  now  on  top  of  the  stack.  If  the 
target  routine  is  an  overlaid  library,  the  run-time  support  ($AUTO) 
loads  the  appropriate  overlay  and  relays  the  transfer  of  control. 

You  may  use  this  vectoring  mechanism  to  isolate  the  linkages  between 
two  libraries  whether  or  not  you  use  them  in  the  cluster  library 
scheme.  You  can  replace  either  the  FORTRAN  OTS  or  the  FCS-11  library 
in  your  system  without  relinking  the  other  library.  However,  you  must 
relink  your  task  when  you  replace  either  of  these  libraries. 
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5.2.1.4   Rul*  3:   Revectored  Entry  Point  Symbols  Must   Not   Appear  In 

th«    "Upstrean"    .STB    rile  -  This   rule   means   that  the 

GBLxdL-symbol  option  must  appear  for  each   revectored   symbol,   as  in 

FORTRAN   OTS   in   this   example.    In   the   brief   example   above,  the 

following  line  must  appear  in  the  build   file   for   the   FORTRAN  OTS 
library: 

GBLXCL-.OPEN 


5.2.1.5  Rule  4:  A  Called  Library  Procedure  Must  Not  Require 
Parameters  on  the  Stack  -  This  rule  applies  to  routines 
contained  in  libraries  other  thar\  the  "default"  library,  as 
represented  by  the  FMSCLS  and  FCSRtS  libraries  of  the  above  example. 
In  addition,  the  called  procedures  must  use  the  JSR  PC  and  RTS  PC  call 
and  return  convention.  The  flow  of  control  for  a  call  into  a  cluster 
library  member  other  than  the  default  proceeds  as  follows. 

Only  your  task  can  call  and  reference  the  FCSRES  library  routine 
.OPEN.  All  references  from  other  libraries  are  revectored  as 
described  above.  TKB  resolves  all  such  references  to  an  appropric.ce 
task  resident  autoload  vector.  As  in  the  example,  when  the  FORTRAN 
OTS  library  calls  .OPEN,  the  code  revectors  the  call  through  your  task 
and  hence  to  the  autoload  vector.  At  this  point,  the  TKB  run-time 
routine  $AUTO  gets  control  and  searches  the  overlay  segment  descriptor 
tree,  noting  which  segments  are  resident  and  which  must  be  loaded  or 
mapped  to  access  the  target  routine. 

Next,  $AUTO  notes  that  a  member  of  a  library  cluster  must  be  unmapped 
to  comply  with  the  map  adjustments  required  to  access  the  target 
routine.  The  reference  to  the  unmapped  library  and  the  segment  within 
the  library  is  placed  on  the  stack,  the  target  library  is  mapped,  and 
the  target  routine  is  accessed  through  a  JSR  PC  instruction.  That 
target  routine  must  not  attempt  to  access  parameters  by  offsets  from 
the  stack  pointer  (SP)  because  of  the  presence  of  $AUTO  saved 
information.  Upon  return  from  the  target  by  an  RTS  PC  instruction, 
the  target  library  is  unmapped,  and  the  previous  library  remapped 
using  the  saved  segment  and  library  data  on  the  stack.  Finally,  $AUTO 
executes  an  RTS  PC  instruction  to  return  to  the  caller. 

Note  that  if  your  task  contains  a  mix  of  cluster  libraries  and 
noncluster  libraries,  the  call  format  rule  applies  only  to  control 
transfers  to  cluster  library  routines.  Other  noncluster  libraries 
that  you  create  may  use  any  appropriate  call  and  parameter  passing 
convention. 


5.2.1.6  Rule  5:  All  the  :.ibraries  Must  be  PIC  or  Built  for  the  Same 
Address  -  TKB  must  be  able  to  place  each  library  of  the 
cluster  at  the  same  virtual  address.  To  do  this,  the  libraries  must 
be  built  as  position  independent  or  be  built  to  the  exact  address 
specified  in  the  CLSTR  command  described  below. 


5.2.1.7  Rule  6:  Trap  or  AsynchronouiS  Entry  Into  a  Library  is  not 
Permitted  -  A  routine  built  as  part  of  a  library  that  is  to 
be  used  in  a  cluster  may  not  be  specified  as  the  service  routine  for  a 
synchronous  trap,  or  for  asynchronous  entry  as  a  result  of  I/O 
completion  or  Executive  service.  This  restriction  is  required  because 
at  the  moment  of  the  trap  or  fault,  the  appropriate  library  may  not  be 
the  one  that  is  mapped.  For  example,  if  the  default  library  contp-^s 
the  service  routine  to  display  an  error  message  upon  odd  address  i  p 
(the  odd  address  fault  occurs  within  one  of  the  other  libraries  of  ^.le 
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clust«r)  ,  the  routine  will  not  be  available  to  service  the  trap.  It 
will  have  been  unmapped  by  the  run-time  routines  to  map  the  called 
1 Ibrary . 

I/O  completion  and  f.iult  service  vectors  and  routines  must  be  placed 
in  libraries  or  tas-  segments  that  are  resident  at  all  times  that  the 
fault,  trap,  or  I/O  completion  may  occur. 


5.2.2   Building  Your  Task 

After  building  the  Individual  libraries  and  placing  the  .TSK  and  .STB 
files  for  all  the  libraries  Into  the  LB: [1,1]  directory,  you  may  build 
your  task.  The  TKB  option  line  that  you  must  use  for  your  task  has 
the  following  syntax: 

CLSTR-llbrary_l , library_2 , . . . library_n: switch :apr 

library_n 

The  first  specification  denotes  the  first  or  the  default  library, 
which  is  the  library  to  which  the  task  maps  when  the  task  starts 
up  and  remaps  after  any  call  to  another  library. 

In  an  RSX-llM  or  RSX-llM-PLUS  S'-stem,  the  total  number  of 
libraries  to  which  a  task  may  ma|-  is  seven.  The  number  of  the 
component  libraries  In  clusters  Is  limited  to  a  maximum  of  six. 
A  cluster  must  contain  a  minimum  of  two  libraries.  It  Is 
possible  to  have  two  clusters  of  three  libraries  each  or  three 
clusters  of  two  libraries  each;  any  combination  of  clusters  and 
libraries  must  equal  at  least  two  or  a  maximum  of  six.  If  six 
libraries  are  used  in  clusters,  the  task  may  map  to  only  one 
other,  separate  library. 

:switch:apr 

The  switch  :RW  or  :R0  indicates  whether  the  cluster  is  read-only 
or  read-write  for  this  particular  task.  The  APR  specification  Is 
optional  and  indicates  which  APR  is  to  be  used  as  the  starting 
APR  when  mapping  to  cluster  libraries.  If  not  specified,  TKB 
assigns  the  highest  available  APRs  and  as  many  as  required  to  map 
the  library. 


5.2.3   Examples 

The  sample  build  files  for  F77CLS,  FDVRES,  and  FCSRES,  and  for  the 
FMS-11  demonstration  task  FMSDEM  are  appended  as  an  example  of  the 
cluster  library-build  process. 


5.2.3.1   F77CLS  —  Build  the  Default  Library  for  the  FORTRAN-77  OTS  - 

>TKB 

TKB>F77CLS/-HD,F7  7CLS/CR/-SP/MA,F77CLS=F77RES 

TKB>LB: [1,1] F7  70TS/LB 

TKB>LB: [1,1]SYSLIB/LB:FCSVEC  ;  INCLUDE  THE  FCS  JUMP  VECTOR 

TKB>/ 

Enter  Options: 

STACK=0 

PAR=F77CLS: 140000:40000 
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; 

;  FORCE  THE  JUMP  TABLE  TO  BE  LOADED  FROM  THE  SYSTEM 
;  LIBRARY  WHEN  THE  USER  TASK  IS  BUILT 

> 

GBLINC".FCSJT 


;  REFERENCE  SYMBOL  DEFINED  IN 
;  THE  MODULE  SYSLIB/LB: FCSJMP 

PREVENT  DEFINITIONS  FOR  FCS-11  ENTRY  POINTS  FROM  APPEARING 
IN  THE  .STB  FILE  FOR  THIS  LIBRARY  OR  OTHER  SYSTEM  LIBRARY 


; 
; 
; 
; 

GBLXCL-. CLOSE 

GBLXCL-.CSIl 

GBLXCL-.CSI2 

GBLXCL-.DLFNB 

GBLXCL=.FINIT 

GBLXCL».GET 

GBLXCL=.GETSQ 

GBLXCL-.GTDID 

GBLXCL-.MRKDL 

GBLXCL=.OPFNB 

GBLXCL-. PARSE 

GBLXCL=. POINT 

GBLXCL-.POSRC 

GBLXCL-.PKINT 

GBLXCL=>.PUT 

GBLXCL=.PUTSQ 

GBLXCL=.SAVR1 

GBLXCL=.READ 

GBLXCL=.WAIT 

// 

The  GBLINC  option  as  shown  above  forces  TKB  to  add  a  global  reference 
entry  in  the  library  .STB  file.  This  ensures  that  TKB  links  certain 
modules  required  by  the  library,  such  as  impure  data  areas  or 
root-only  routines,  without  further  user  action.  These  modules  should 
be  in  the  system  library  (LB: [1 , 1) SYSLIB.OLB)  or  in  a  library  always 
referenced  by  your  task,  so  that  this  forced  loading  mechanism  is 
entirely  invisible  to  you. 


5.2.3.2   FDVRES  —  Build  an  PMS-11/RSX  VI. 0  Shareable  Library  - 

TITLE  OF  THE  EXAMPLE  COMMAND  FILE  THAT  BUILDS  THE  FORMS 
MANAGEMENT  PLAS-RESIDENT  LIBRARY  FOR  USE  WITH  THE 
TASK  BUILDER  CLSTR  OPTION. 

FDVRES.CMD 

THE  FOLLOWING  CODE  IS  THE  EXAMPLE  COMMAND  FILE: 

LB: [1 ,1]FDVRES/-HD/MM/SG,MP: [1 ,34] FVRES/MA/-SP, LB : [1,1)FDVRES= 

SY: [1,24] FDVRESBLD/MP 

STACK=0 

PAR=FDVRES: 140000:40000 

TASK=FDVRES 

THE  FOLLOWING  LINE  FORCES  THE  FCS  JUMP  TABLE  TO  BE  INCLUDED  IN  THE 
SYMBOL  TABLE  FILE  FOR  THE  FORMS  MANAGEMENT  LIBRARY. 

GBLINC=.FCSJT 
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; 

;  THE 

;  THE 

; 

GBLREF 

GBLREF 

GBLREF 

GBLREF 

GBLREF 

GBLREF 

GBLREF 

GBLREF 

GBLREF 

GBLREF 

GBLREF 

GBLREF 

GBLREF 

GBLREF 

GBLREF 

GBLREF 

GBLREF 

GBLREF 

GBLREF 

GBLREF 

GBLREF 

GBLREF 

GBLREF 

; 

;  THE 
;  FROM 


FOLLOWING  LINES  FORCE  LIBRARY  ENTRY  POINTS 
TASK  ROOT J 


AND  DEFINITIONS  INTO 


CB$CUR 
"DV$GRA 
D$LNCL 
D1$ARY 
D2$FUL 
FC$ALL 
FC$OPN 
FC$SPF 
FE$FCH 
FE$IMP 
FE$UTR 
FT$SBK 
F$FNC, 
F$TRM, 
IS$HLP 
I$ALLC 
I$DISP 
I$FDS1 
I$FXD2 
I$LNCL 
I$RESP 
=L$LNCL 
=  $FDV 


,CB$REV, 
,DV$REV, 
,D$PICT, 
,DI$COM, 
,D2$NEC, 
,FC$ANY, 
,FC$PAL, 
,FC$SPN, 
,FE$FLB, 
,FE$INI, 
,FE$INC, 
,FT$SFW, 
F$IMP,F$ 
F$VAL,IS 
,IS$INS, 
, I$BADR, 
, I$DLN1, 
,I$FDS2, 
, I$HLEN, 
,I$LPTR, 
,I$ROFF, 
,L$RESP, 


CB$TST,CB$132 
DV$UND,D$ATT1 
D$PLEN,D$RLEN 
D1$MIX,D1$NUM 
D2$REQ,D2$RTJ 
FC$CLS,FC$CSH 
FC$PSC,FC$PUT 
FC$TRM,FE$ARG 
FE$FLD,FE$FNM 
FE$IOL,FE$IOR 
FS$SUC,FT$ATB 
FT$SNX,FT$SPR 
LEN,F$NAM,F$N 
$ALT,IS$CLR,I 
IS$LST,IS$MED 
I$BEND,I$BPTR 
I$DLN2,I$FADR 
I$FIXD,I$FMST 
I$HLPF,I$ILEN 
I$LVID,I$NBYT 
I$STAT, I$STKP 
$$FDVT 


,DV$BLD, 
,D$ATT2, 
,D$VATT, 
,D1$SCR, 
,D2$SP0, 
,FC$DAT, 
,FC$RAL, 
,FE$DLN, 
,FE$FRM, 
,FE$LIN, 
,FT$KPD, 
.,FT$XBK, 
IUM,F$REQ 
S$DEC,IS 
■,IS$NMS, 
,I$BSIZ, 
,I$FBLK, 
,I$F0FF, 
,I$IMPA, 
,I$NDAT, 
,I$SVST, 


DV$BLK, 
D$CLRC, 
D$2ATT, 
D1$SNM, 
D2$TAB, 
FC$GET, 
RC$RTN, 
FE$DNM, 
FE$FSP, 
FE$NOF, 
FT$NTR, 
FT$XFW, 
,F$RSIZ 
$ DSP, IS 
IS$SCR, 
I$CFRM, 
I$FCHN, 
I$FORM, 
I$LCOL, 
I$NFLD, 
I$VATT, 


DVSDHW 
D$FID, 
DISALN 
D2$DEC 
D2$VRT 
FC$GSC 
FC$SHO 
FE$DSP 
FE$ICH 
FE$NSC 
FT$NXT 
F$ASIZ 
,F$STS 
$ERR,I 
IS$SGN 
I$CURC 
I$FDES 
I$FSIZ 
I$LINE 
I$PATN 
L$CLSZ 


,DV$DWD 

D$FXLN 

,D1$ALP 

,D2$DIS 

,D2$ZFL 

,FC$LST 

,FC$SLN 

,FE$FCD 

,FE$IFN 

,FE$STR 

,FTSPRV 

,F$CHN 

S$HFM 

,I$ADVO 

,I$CURP 

,I$FDST 

,I$FXD1 

,I$LLIN 

,I$PBLN 

,L$FDES 


FOLLOWING  LINES  PREVENT  THE  DEFINITIONS  FOR 
APPEARING  IN  THE  FORMS  MANAGEMENT  LIBRARY 


FCS-11  ENTRY  POINTS 
.STB  FILE: 


GBLXCL" 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 
GBLXCL= 


.ASCPP 

.ASLUN 

.CLOSE 

.CTRL 

. DELET 

.DLFNB 

.ENTER 

.EXTND 

.FATAL 

.FCTYP 

.FIND 

.FINIT 

.FLUSH 

.GET 

.GETSQ 

.GTDID 

.GTDIR 

.MARK 

.MBFCT 

.MRKDL 

.OPEN 

.OPFID 

.OPFNB 

.PARSE 

.POINT 

.POSIT 

. POSRC 

.PPASC 

.PPR50 

.PRINT 
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GBLXCL- 

.PRSDI 

GBLXCL- 

. PRSDV 

GBLXCL- 

. PRSFN 

GBLXCL- 

.PUT 

GBLXCL- 

. PUTSO 

GBLXCL- 

•RDFDR 

GBLXCL- 

.RDFFP 

GCLXCL- 

.RDFUI 

GBLXCL- 

.SAVRl 

// 

5.2.3.3   FDVRESBLD.ODL  —  Overlay 
Cluster  Library  - 


Description   for   FMS-11/RSX   VI. 0 


.ODL  FILE  FOR  THE 


THE  FOLLOWING  LINE  IS  THE  FILENAME  OF  THE 
PLAS-RESIDENT  FORMS  MANAGEMENT  LIBRARY: 

FDVRESBLD.ODL 


THE  FOLLOWING  LINES  OF  CODE  ARE  CONTAINED  IN  THE  .ODL  FILE  FOR  THE 
PLAS-RESIDENT  FORMS  MANAGEMENT  LIBRARY: 


FDVROT 

FDVROT-*! (MAIN,NULO) 
LB:  [l,l]SYSLIB/LB:NULr. 
LB:  [1,1]SYSLIB/LB:FCSVEC 
LB:  [1,1]  FDV'.IB/LB:FDV-LB! 


.NAME 

•  ROOT 

NULO: 

.FCTR 

FCSV: 

.FCTR 

MAIN: 

.FCTR 

.END 

[1,1]FDVLIB/LB-FCSV 


5.2.3.4  FCSRES  Library  Build  -  FCSRSIBLD.BLD  is  distributed  with  the 
RSX-llM  and  RSX-llM-PLUS  distribution  kits.  Refer  to  the  build 
command  and  overlay  description  contained  in  the  files  FCSRS1BLD.CMD 
and  FCSRSIBLD.ODL,  which  can  be  generated  by  SYSGEN  if  you  want. 


5.2.3.5   F77TST.CMD  ~  File  to  Build  the  FMS-11/RSX  VI. 0   FORDEM 
Task  - 


Test 


FORDEM/FP , FORDEM/MA/-SP=FORDEM , HLLFOR 

LB; [1,1]FDVLIB/LB 

LB: [1,1]F770TS/LB 

/ 

EXTSCT=$$FSR1:2000 

CLSTR=F7  7CLS , FDVRES , FCSRES : RO 

STACK=200 

// 


5.2.4   Overlay  Run-Time  Support  Requirements 

The  Task  Builder  uses  the  .STB  files  of  the  cluster  libraries  to 
obtain  the  information  needed  to  create  the  overlay  data  base.  For 
each  PLAS  overlaid  cluster  library  TKB  places  autoload  vectors, 
segment   descriptors,   window  descriptors,  and  a  region  descriptor  in 
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the  root  of  the  task.  This  information  comprises  the  overlay  run-ttme 
support  for  the  cluster  libraries.  In  Appendix  B,  Figure  B-9  and  the 
accompanying  text  describe  this  inform.it  i  on .  Table  5-1  describes  the 
space  needed  for  the  overlay  run-time  system  support  that  includes 
cluster  libraries.  For  a  complete  description  of  overlay  run-time 
routine  sizes,  see  Section  4.5. 

Using  cluster  libraries  conserves  virtual  space  and  may  require  only 
one  window. 


Table  5-1 
Comparison  of  Overlay  Run-Time  Module  Sizes 


Module 


Program 
Sect  ion 


Number 
of  Bytes 
Oct /Dec 


Specific  Use 


One  of  the  following  modules  is  included  in  any  overlaid  task 
that  uses  autoload  and  in  any  task  that  links  to  a  PLAS  overlaid 
resident  library. 


AUTO 
AUTOT 


$$AUTO    122/82. 


$$AUTO 

$$RTQ 

$$RTR 


132/90. 
32/26. 
30/24. 


All  tasks  that  use  autoload 

All  tasks  with  AST's 
disabled  during  autoload 


# 


One  of  the  following  modules  is  included  in  any  overlaid 
conventional  task.  OVCTR  or  OVCTC  is  included  in  any 
non-overla'd  task  {conventional  or  I-  arid  D-  8p«ce)  that  links 
to  d  PLAS  overlaid  resident  library. 


OVCTL      $$MRKS     76/62. 
$$RDSG    160/112. 
$$PDLS      2/2. 


Disk  overlays  only 


OVCTR  $$MRKS  234/156. 
$$RDSG  332/218, 
$$PDLS     12/10. 


Disk  and  PLAS  overlays  with  no 
cluster  libraries 


OVCTC  $$MRKS  254/172. 
$$RDSG  352/234. 
$$PDLS    120/80. 


Disk  and  PLAS  overlays 
with  cluster  libraries 


One  of  the  following  three  modules  is  included  in   any   overlaid 
I-  and  D-space  task. 


OVIDL 


$$MRKS 
$$RDSG 
$$PDLS 


76/62. 

224/148. 

2/2. 


Disk  overlays  only 


OVIDR 


$$MRKS 
$$RDSG 
$$PDLS 


304/196. 

502/322. 

12/10. 


Disk  and  PLAS  overlays 
with  no  cluster  libraries 


OVIDC 


$$MRKS 
$$RDSG 
$$PDLS 


324/212. 
522/338. 
120/80. 


Disk  and  PLAS  overlays 
with  cluster  libraries 


(continued  on  next  page) 
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Table  5-1  (Cont.) 
Comparison  of  Overlay  Run-Time  Module  Sizes 


Module 


Program 
Sect  ion 


Number 
of  Bytes 
Oct/Dec 


Specific  Use 


The  overlay  data  vector  OVDAT  is  included  in  any   overlaid   task 
and  in  any  task  that  links  to  a  PLAS  overlaid  resident  library. 


OVDAT 


$$OVDT 

24/20 

$$SGDO 

0/0. 

$$SGD2 

2/2. 

$$RTQ 

0/0. 

$$RTR 

0/0. 

$$RTS 

2/2. 

Included  in  all  tasks 
that  perform  ov<»rlay 
operations 


The  overlay  error  service  routine   ALERR   is   included   whenever 
OVDAT  is  included. 


ALERR 


$$ALER 


24/20, 


Overlay  error 


Manual  overlay  control  (LOAD)  is   used   in   place   of   any   AUTO 
routine.   (See  Section  4.2,  Manual  Load.) 


LOAD 


$$LOAD 
$$AUTO 


252/170. 
14/12. 


Manual  overlay  control 


5.3   VIRTUAL  PROGRAM  SECTIONS 

A  virtual  program  section  is  a  special  TKB  storage  allocation  facility 
that  permits  you  to  create  and  refer  to  large  data  structures  by  means 
of  the  mapping  directives.  Virtual  program  lections  are  supported  in 
TKB  through  the  VSECT  option  and  in  FORTRAN  through  a  set  of 
FORTRAN-callable  subroutines  that  issue  the  necessary  mapping 
directives  at  run  time.  With  the  TKB  VSECT  option,  you  can  specify 
the  following  parameters  for  a  relocatable  program  section  or  FORTRAN 
common  block  that  you  have  defined  in  your  object  module: 

•  Base  virtual  address 

•  Virtual  length  (window  size) 

•  Physical  length 

By  specifying  the  base  address,  you  can  align  the  program  section  on  a 
4K  address  boundary  as  required  by  the  mapping  directives. 
Thereafter,  references  within  the  program  need  only  point  to  the  base 
of  the  program  section  or  to  the  first  element  in  the  common  block  to 
ensure  proper  boundary  alignment. 

By  specifying  the  window  size,  you  can  fix  the  amount  of  virtual 
address  space  that  TKB  allocates  to  the  program  section.  If  the 
allocation  made  by  a  module  causes  the  total  size  to  exceed  this 
limit,  the  allocation  wraps  around  to  the  beginning  of  the  window. 
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By  Specifying  the  physical  size,  you  can  allocate,  before  run  timt, 
the  phyalcal  memory  that  the  program  section  will  be  mapped  into  at 
run  time.  TKB  allocates  this  physical  memory  within  an  area  that 
precedes  the  task  image.   This  area  is  called  the  mapped  array  area. 

TKe  physical  length  parameter  is  optional.  If  you  intend  to  allocate 
physical  memory  at  run  time  tiirough  the  Create  Region  directive,  you 
can  specify  a  value  of  0. 

Note  that  when  you  specify  a  nonzero  value  for  the  physical  memory 
parameter,  the  rasulting  allocation  affects  only  the  tasK'a  memory 
image,  not  its  disk  image. 

Note  also  that  TKB  attaches  the  virtual  attribute  to  a  relocatable 
program  section  you  have  specified  in  the  VSECT  option  only  if  the 
section  is  defined  in  the  coot  segment  of  your  task  through  either  a 
FORTRAN  COMMOK  or  a  MACRO-11  .PSECT  statement.  The  relocatable 
program  section  with  the  virtual  attribute  in  the  root  does  not  use 
address  space  in  your  task;  using  this  procedure  merely  assigns  an 
address,  window  size,  and  physical  length  to  a  region  yet  to  be  mapped 
at  run  time  by  your  task.   For  example: 

TKB>VSECT=»MARRAY:  160000:  20000:  2000 

In  this  example,  virtual  program  section  MARRAY  is  allocated   with   a 

window   size   of   4K   words   (20000   (octal)  bytes)  and  a  base  virtual 

address  of  160000.  In  physical  memory,  32K  words  are  reserved  for 
mapping  the  section  at  run  time. 


Assume  the  program  is  written  in  FORTRAN,  and  includes 
statement : 


the   following 


COMMON  /MARRAY/ARRAY(4) . . . 

This  statement  generates  a  program  section  to  which  TKB  attaches  the 
virtual  attribute.  However,  this  program  section  is  not  a  FORTRAN 
virtual  array.  A  reference  to  the  first  element  of  the  section, 
ARRAY(l),  is  translated  by  TKB  to  the  virtual  address  160000. 

Figure  5-14  shows  the  effect  of  this  use  of  the  VSECT  option. 

As  mentioned  previously,  TKB  restricts  the  amou  ,t  of   virtual  address 

space   allocated   to  the  section  to  a  value  that  is  less  than  or  equal 

to  the  window  size,  wrapping  around  to  the  base  if  the  window  size  is 
exceeded . 

This  process  is  illustrated  in  the  following  example,  in  which  three 
modules.  A,  B,  and  C,  each  contain  a  program  section  named  VIRT  that 
is  3000  words  long.  A  window  size  of  4K  words  has  been  set  through 
the  VSECT  option.  If  the  program  section  has  the  concatenate 
attribute,  the  Task  Builder  allocates  memory  to  each  module  as 
follows : 


Module 

A 

B 
C 


Low  Limit 

160000 
174000 
170000 


Length 

14000 
14000 
14000 


High  Limit 

174000 
170000 
164000 


The  address  limits  for  modules  B  and  C  illustrate  the  effect  of 
address  wrap-around  when  a  component  of  the  total  allocation  exceeds 
the  window  boundary.  Note  that  the  addresses  generated  will  be 
properly  aligned  with  the  contents  of  physical  memory  if  the  virtual 
section  is  remapped  in  increments  of  the  window  size. 
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160000  APR  7  — 
APR6  — 
APR  5  — 
APR4  — 
APR  3  — 


APR  2- 


APR  1 


APR  0- 


WINDOW 


TASK 

IMAGE 


Q    (PROGRAM 
SECTION 
DEFINITION) 

COMMON/MARRAY/ 


HEADERS,  STACK 


} 


O  (WINDOW  SIZE) 


X 


9  (VIRTUAL  BASE  ADDRESS) 


VIRTUAL  ADDRESS 
SPACE 


TKB  >/ 

ENTER  options: 

TKB    VSECT    MARRAY:160000:20000:2000 


o 

PHYSICAL  LENGTH 
64-BYTE  BLOCKS 


o    o   o  o 


TASK 

IMAGE 


COMMON/MARRAY/ 


HEADER  &  STACK 


MAPPED 

ARRAY 

AREA 


*www^^i""»ww!" 
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Figure  5-14   VSECT  Option  Usage 
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S.3.1   FORTRAN  Run-Time  Support  for  Virtual  Program  Sections 

KORTRAN  supports  subroutines  to  make  use  of  the  mappirig  dicectiv/es. 
FORTRAN  also  supports  calls  to  the  following  subroutines,  which  are 
related  to  virtual  program  sections: 

Subroutine  Function 

ALSCT      Allocates  a  portion  of  physical  memory   for   use  as   a 
virtual  section 

RLSCT      Releases  all  physical  memory   allocated   to   a   virtual 
section 

As  mentioned  earlier,  the  effect  of  one  or  more  VSECT-  declarations  at 
task-build  time  is  to  create  a  pool  of  physical  memory  below  the  task 
image  (the  mapped  array  area).  Before  a  virtual  section  is  referred 
to,  the  task  must  allocate  a  portion  of  this  memory  through  a  call  to 
ALSCT.  When  space  is  no  longer  required,  it  is  released  through  a 
call  to  RLSCT. 

Note  that  these  subroutines  issue  no  mapping  directives.  They 
allocate  and  release  space  using  region  and  window  descriptor  arrays 
that  you  supply.  The  resulting  physical  offsets  are  used  in  the 
task's  subsequent  calls  that  perform  the  actual  mapping. 

The  subroutine  ALSCT  is  called  to  allocate  physical  memory  to  a 
virtual  program  section  as  follows: 

CALL  ALSCT  ( i reg , i wnd [ , ists] ) 

ireg 

A  one-dimensional  integer  array  that  is  nine  words  long. 
Elements  1  through  8  of  the  array  contain  a  region  descriptor  for 
the  physical  memory  to  be  mapped.  The  descriptor  has  the 
following  format: 

ireg(l)    Region  ID. 

ireg(2)    Size  of  region  in  units  of  64-byte  blocks. 

ireg(3)  Name  of  region  in  Radix-50  format  (first  three 
characters) . 

ireg (4)  (Second  three  characters). 

ireg(5)  Name  of  main  partition  containing  region. 

ireg(6)  The  name  is  in  Radix-50  format. 

ireg(7)  Region  status  word. 

ireg(8)  Region  protection  code. 

ireg(9)  Thread  word:  This  element  links  window  descriptors 
that  are  used  to  map  portions  of  the  region.  It  is 
maintained  by  the  subroutine. 

The  elements  of  the  array  that  you  set  up  consist  of  ireg(l)  and 
ireg(3)  through  ireg(8).  The  thread  word,  irGg(9),  must  be  0  on 
the  initial  call;   thereafter,  the  subroutine  maintains  it. 
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When  your  task  makes  an  allocation,  Ireg(l)  and  ireg(2)  muat  be  0 
on  the  Initial  call.  In  this  case,  ALSCT  obtains  and  stores  the 
region  size  in  ireg(2).  When  the  allocation  is  being  made  from  a 
separate  region,  the  caller  must  supply  both  region  ID  and  size. 
The  subroutine  does  not  refer  to  elements  3  through  8  but  rather 
the  caller  must  set  them  up  as  required  by  the  applicable  system 
directives.  For  a  detailed  description  of  these  parameters, 
refer  to  the  RSX-llM/M-PLUS  Executive  Reference  Manual. 


Iwnd 


A  one-dimensional  array  '.hat  is  11  words  long.  The  first  eight 
words  contain  a  window  dtscriptor  in  the  following  format: 

iwnd(l)  Base  APR  in  bits  8  through  15;  the  Executive  sets 
bits  0  through  7  when  the  appropriate  mapping 
directives  are  issued. 

iwnd (2)  Virtual  base  address. 

iwnd (3)  Window  size  in  units  of  64-byte  blocks. 

iwnd(4)  Region  ID. 

iwnd(5)  Offset  into  the  region,  in  units  of  64-byte  blocks. 

iwnd (6)  Length  to  map,  in  units  of  64-byte  blocks. 

iwnd (7)  Status  word. 

iwnd (8)  Address  of  send/receive  buffer. 

iwnd (9)  Base  offset  of  physical  block  allocated  to  section 
in  units  of  64-byte  blocks. 

iwnd(lO)  Length  of  block  in  jnits  of  64-byte  blocks  (supplied 
by  caller);  set  to  maximum  block  offset  by 
subroutine. 

iwnd(ll)  Thread  word:  This  element  links  window  descriptors 
that  are  used  to  map  other  portions  of  the  region. 
It  is  maintained  by  the  subroutine. 

You  must  set  up  IWND(IO)  before  calling  ALSCT. 

The  following  array  elements  are  supplied  as  output  from  the 
subroutine: 

iwnd (4),  iwnd (5),  iwnd (9),  iwnd (10),  and  iwnd (11) 

The  remaining  elements  must  be  set  up  as  required  by  the 
Executive  directives.  Consult  the  RSX-llM/M-PLUS  Executive 
Reference  Manual  for  a  detailed  descriptTon  of  these  parameters. 
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ists 

An  area  that  receives   the   result   of   the   call.    One   of   the 
following  values  Is  returned: 

♦I  Block  successfully  allocated.  In  this  case,  the  region 
and  window  descriptor  arrays  are  set  up  as  described 
above . 

-200.  Insufficient  physical  memory  was  available  for 
allocating  the  block 

The  subroutine  RLSCT  is   called   to  deallocate   the  physical   memory 
assigned  to  a  virtual  section  as  follows: 


ireg 


CALL  RLSCT  (ireg,iwnd) 


A  one-dimensional  integer  array  that  is  nine  words  long.  The 
contents  of  the  array  are  the  same  as  those  described  for 
subroutine  ALSCT. 

iwnd 

A  one-dimensionax  integer  array  that  is  11  words  long.  The 
contents  of  the  rray  are  the  same  as  those  described  for 
subroutine  ALSCT. 

Upon  return,  element  iwnd  (10)  is  the  leng»-h  of  the  deallocated 
region  in  units  of  64-byte  blocks. 

The  procedure   for   using   these   subroutines   can   be   summarized   as 
follows: 

1.  You  allocate  storage  in  the  program  for  one  window  descriptor 
per  VSECT,  and  for  a  single  region  descripto-. 

2.  Your  task  calls  the  subroutine  ALSCT  to  reserve  the  physical 
memory  to  which  the  program  section  will  be  mapped. 

3.  Your  task  issues  the  mapping  directives  to  map  the  virtual 
address  space  into  a  portion  of  the  physical  memory.  It  is 
the  task's  responsibility  to  ensure  that  the  physical  memory 
to  be  mapped  is  always  within  the  limits  defined  by  iwnd (9) 
and  iwnd  (10)  . 

4.  When  the  space  is  no  longer  required,  the  task  unmaps  it  and 
releases  it  with  a  call  to  RLSCT. 


5.3.2   Example  5-5:   Building  a  Program  that  Uses   a   Virtual   Program 
Section 

Example  5-5,  Part  1  shows  the  FORTRAN  source  file  for  a  task  named 
VSECT. FTN.  It  illustrates  the  use  of  the  ALSCT  FORTRAN  subroutine. 
When  you  build,  install,  and  run  VSECT,  it  will  allocate  the  mapped 
array  area  below  its  header,  create  a  4K-word  window,  and  map  to  the 
area  through  the  window.  ALSCT  will  then  initialize  the  area  and 
prompt  for  an  array  subscript  at  your  terminal  by  printing: 

SUBSCRIPT? 
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When  you  input  a  subscript,  it  responds  with  ELEMENT-  and  the  contents 
of  the  array  element  for  the  subscript  you  typed.  VSECT  continues  to 
prompt  until  you  type  CTRL/Z.   Upon  receiving  a  CTRL/Z,  VSECT  exits. 

Once  you  have  compiled  VSECT,  you  can  build  it  with  the  following  Trsk 
Builder  command  sequence: 

TKB>VSECT,VSECT/-SP»VSKCT,LB: [1,1 IFOROTS/LB 

TKB>/ 

Enter  Options: 

TKB>WNUWS"1 

TKB>VSECT«MARRAY:  160000:  20000:  200 

TKB>// 

This  command  sequence  directs  TKB  to  create  a  task  image  file  named 
VSECT. TSK  and  a  short  (by  default)  map  file  VSECT. MAP.  Because  /-SP 
is  appended  to  the  map  file,  TKB  does  not  output  the  map  to  the  line 
pr  inter . 

The  library  switch  (/LB)  specifies  that  TKB  is  to  search  the  FORTRAN 
run-time  library  FOROTS.OLB  to  resolve  any  undefined  refe'^nces  in  the 
input  module  VSECT. OBJ.  Because  the  library  switch  was  applied  to  the 
FORTRAN  library  file  without  arguments,  TKB  extracts  from  the  library 
and  includes  in  the  task  image  any  modules  in  which  references  are 
def  ined . 

The  WNDWS  option  directs  TKB  to  add  a  window  block  to  the  header  in 
the  task  image.  The  Executive  initializes  this  window  block  when  it 
processes  the  mapping  directives  within  the  task. 

The  VSECT  option  directs  TKB  to  establish  for  the  program  section 
named  MARRAY  a  base  address  of  160000  (APR  7)  and  a  length  of 
20000(octal)  bytes  (4K  words).  The  program  section  VIR"^  is  defined 
within  the  task  through  the  FORTRAN  COMMON  statement.  The  VSECT 
option  also  specifies  that  TKB  is  to  allocate  200  64-byte  blocks  of 
physical  memory  in  the  task's  mapped  array  area  below  the  task's 
header.  (For  more  information  on  the  switches  and  options  used  in 
this  example,  rtfer  to  Chapters  10  aid  11.) 

The  map  that  results  from  this  command  sequence  is  shown  in  Example 
5-5,  Part  2. 

Exai.iple  5-5,  Part  1   Source  Listing  for  VSECT. FTN 

C 

C         VSECT. FTN 


c 


INTEGER  *2  SUB , I RDB ( 9 ) , I WDB ( 1 1 ) , DSW 

INTEGER  *2  IARRAY(4096) 

COMMON  /MARRAY/IARRAY 

IWDB  (1)  =  "34J0  !USE  APR  7  FOR  WINDOW 

IWDB  (3)  =  128  'WINDOW  SIZE  =  128*32  WORDS  =  4K 

IWDB  (5)  =  0  iOFFSET 

IWDB  (7)  =  "402  iSTATUS  =  WS . 64B ! WS . WRT 

IWDB  (10)  =  128  !SIZE  TO  ALLOCATE 

(continued  on  next  page) 
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e 

C        ALLOCATE  4K  MAPPED  ARRAY  TO  IWDB.IRDB 

e 

CALL  ALSCT  ( I RDB, IWDB, DSW) 
IF  (DSW  .NE.  1)  GOTO  100 

c 

C        Ckl::ATE  A  4K  ADDRESS  WINDOW 

c 

CALL  CRAW  (IWDB,DSW) 

IF  (DSW  .NE.  1)  GOTO  200 

c 

C        MAP  4K  MAPPED  ARRAY 

c 

CALL  MAP  (IWD3,DSW) 
IF  'DSW  .NE.  1)  GOTO  300 
DO  1  I"l,4096 
1        lARRAY  (I)  >  I 

c 

C       MAPPED  ARRAY  IS  INITIALIZED,  PROMPT  FOR  A  SUBSCRIPT 
C 

3  WRITE  (5,5) 

5  FORMAT  ( 'SSUBSCRIPT?' ) 
READ  (5,4,END-1000)SUB 

4  FORMAT  (17) 

WRITE  (5,6)IARRAY  (SUB) 

6  FORMAT  (  '  ELEMENT  -  ',17) 
GOTO  3 

C 

C        ERROR  ROUTINES 

C 

100  WRITE  (r,101)DSW 

101  FORMAT  ('  ERROR  FROM  ALSCT.  ERROR  =  ',17) 
GOTO  1000 

200  WRITE  (5,201)DSW 

201  FORMAT  ('  ERROR  FROM  CREATING  ADDREb"?  WINDOW,  ERROR  -  ',17) 
GOTO  1000 

3C0      WRITE  (5,301)DSW 

301      FORMAT  ('  ERROR  FROM  MAPPING.  ERROR  =  ',17) 
1000     CALL  EXIT 
END 
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Example    5-5,    Part    2      Task    Builder    Map    fo      VSECT.TSK 


VSECT.TSKjl  Memory   allocation   map      TKB   M40.10  Page    1 

ll-DEC-82         16:12 


Partition  Name  :  GEN 

Identification  ;  FORV02 

Task   UIC      :  1303,11 

Stack     llmlta:  000300  001277  001000  00512. 

PRG  xfr  address:  016270 

Total  address  windows:  2. 

Mapped  array  area:  409C.  wordn 

Task   image   size   :  8736.  words 

Task  address  limits:  000000  042043 

R-W  disk  blk  limits:  000002  000044  000043  00035. 

*•*  Root  segment:  VSECT 


R/W  mem   limits:  000000  042043  042044  17444. 
Disk  blk  limits:  000002  000044  000043  0003'i. 


Memory  allocation  synonsis: 
Section 


Title    Ident   File 


.  BLK. : (RW, I,LCL,REL,CON)  001300  001160  00624. 

MARRAY: (RW,D,GBL,REL,OVR)  160000  020000  08192. 

160000  020000  08192. 

OTS$F  : (RW, . ,GBL,REL,CON)  002460  002332  01242. 

002460  000406  00262. 

003066  001724  00980. 

OTS$I  :  (RW,  I,LCL,REL,CO'l)  005012  011220  04752. 


.MAIN.  FORV02  VSECT. OBJ; 3 

$CONVI  F40003  FOROTS . OLB; 2 
$FIO    F40006  FOROTS. 0LB;2 


Global  symbols: 

ADISIA  005032-R   CAL$   005140-R   ICI$    022466-R   MOI$PS  006050-R 


***  Task  builder  statistics: 

Total  work  file  references:  27855. 

Work   file   reads:  0. 

Work   file  writes:  0. 

Size  of  core  pool:  7086.  words  (27. 

Size  of  work  file:  4325.  words  (17, 

Elapsed  time:00 :00:29 


PAGES) 
PAGES) 
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PRIVILEGED  TASKS 


6.1   INTRODUCTION 

This   chapter   discusses   privileged   tasks:    what   they   are,   their 
possible  hazards,  how  they  are  mapped,  and  an  example  of  their  usage. 


6.2   PRIVILEGED  AND  NONPRI VILEGED  TASK  DISTINCTION 

RSX-llM/M-PLUS  systems  have  two  classes  of  tasks:  privileged  and 
nonpr ivi leged .  The  distinction  between  privileged  and  nonpr i vileged 
tasks  is  primarily  based  upon  system-access  capabilities.  Because  all 
tasks  in  an  unmapped  system  have  access  to  all  of  memory,  this 
distinction  is  not  hardware  enforceable.  Therefore,  if  your  system  is 
unmapped,  your  task  must  be  responsible  for  observing  the  access  rules 
of  your  system. 

In  a  mapped  system,  privileged  tasks  have  special  device  and  memory 
access  rights  that  nonpr ivi leged  tasks  do  not  have.  A  privileged  task 
can,  with  certain  exceptions,  access  the  Executive  routines  and  data 
structures;  a  nonpr ivi leged  task  cannot.  Some  privileged  tasks  have 
automatic  I/O  page  mapping  a.'ailable  to  them;  nonpr  i  vi  leged  tasks  do 
not.  Finally,  a  privileged  task  can  bypass  system  security  features, 
whereas  a  nonpr ivi leged  task  cannot. 


6.3   PRIVILEGED  TASK  HAZARDS 

Because  of  their  special  access  rights,  privileged  tasks  are 
potentially  hazardous  to  a  running  system.  A  privileged  task  with 
coding  errors  can  corrupt  the  Executive  or  system  data  structures. 
Moreover,  problems  caused  by  such  a  privileged  task  can  be  obscure  and 
difficult  to  isolate.  For  these  reasons,  you  must  exercise  caution 
when  developing  and  tunning  a  privil'^ged  task. 

Make  certain  that  your  privileged  task  has  completed  its  operation 
when  you  log  off  the  system  (type  BYE).  BYE  does  not  abort  privileged 
tasks  as  it  does  nonpr ivi leged  tasks  because  the  privileged  task  may 
be  in  the  process  of  changing  the  system  data  base.  Therefore,  it 
must  be  allowed  to  complete  its  processing.  Also,  if  the  privileged 
task  is  in  system  state,  neither  BYE  nor  any  other  task  can  execute 
until  the  privileged  task  completes  its  processing  while  in  system 
state.  However,  when  the  privileged  task  leaves  syste.n  state,  BYE 
runs  and  logs  you  off  the  system,  leaving  the  privileged  ask  still  in 
operation. 
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If  a  p>  tcessor  trap  occurs  in  a  privileged  task  while  the  task  is  in 
use  ut...te,  the  Executive  aborts  the  task.  However,  if  the  processor 
trap  occurs  in  the  privileged  task  while  the  task  is  in  system  state, 
the  .'iys.9m  crashes.  However,  even  while  in  user  state  the  privileged 
task  that  is  mapped  to  the  Executive  can  cause  a  system  crash  by 
incorrectly  changing  system  data.  Please  note  that  a  privileged  task 
in  user  state  should  not  be  modifying  system  data. 

All  tasks  in  an  unmapped  system  can  access  all  of  memory.  The 
privileged  or  nonpr i v i leged  designation  has  no  particular  meaning  in 
an  unmapped  system.  Therefore,  be  just  as  careful  about  modifying 
Executive,  device,  or  user  data  in  an  unmapped  system. 


6.4   SPECIFYING  A  TASK  AS  PRIVILEGED 

You  designate  a  task  as  privileged  with  the  /PR  (privileged)  TKB 
switch  (this  switch  is  described  in  Chapter  10).  TKB  allocates 
address  space  for  a  privileged  task  based  on  the  memory  management  APR 
that  you  specify  as  an  argument  to  this  switch.  The  argument  is 
optional;  the  default  is  5  but  you  can  change  it  by  modifying  the 
TKBBLD.CMD  file  and  rebuilding  TKB.  TKB  accepts  three  arguments:  0, 
4,  and  5.  Choosing  which  of  these  arguments  to  specify  is  based  on 
the  considerations  described  below. 


pr  i vi leged 
ress  space 


6.5   PRIVILEGED  TASK  MAPPING 

When  you  specify  an  argument  of  0,  your  task  in  marked   as 
but   not   mapped   to  the  Executive  or  I/O  page.   Virtual  add      ^ 
begins  at  virtual  address  0  and  extends  upward  as  far   as   32K   words. 
Your  task  cannot  access  the  Executive  routines  or  data  structures,  and 
TKB  does  not  reserve  an  APR  to  map  the  I/O  page. 

When  you  specify  /PR:4  or  /PR:5,  TKB  reserves  APR  7  for  mapping  the 
I/O  page.  Moreover,  TKB  makes  the  Executive  available  to  your  task  by 
reserving  the  APRs  necessary  to  map  the  Executive  into  your  task's 
virtual  address  space.  Therefore,  if  your  task  requires  access  to  the 
Executive,  you  must  specify  an  argument  of  either  4  or  5.  However,  5 
is  the  default. 

The  choice  between  APR  4   and   5   is   dictated   by   the   size   of  the 

Executive   area.    If   the   Executive   is   16K   words  or  less,  you  may 

specify  an  argument  of  4  or  5.   The  value   specified   depends   on  the 

task  size.  A  /PR:4  task  can  be  12K  in  size  and  map  the  I/O  page.  TKB 
applies  a  bias  of  100000  (16K)  to  all  addresses  within  your  task. 

If  the  Executive  is  20K  words,  you  must  specify  an  argument  of  5.  TKB 
applies  a  bias  of  120000  (20K)  to  all  addresses  within  your  task. 

The  mapping  for  privileged  tasks  is  shown  in  Figure  6-1. 

The  mapping  for  APR  4  and  5  is  shown  in  Figure  6-2. 

When  you  specify  an  argument  of  4,  there  will  be  12K  words  of  address 
space  between  the  beginning  of  the  task  and  the  start  of  the  mapping 
for  the  I/O  page.  If  your  task  expects  to  access  the  I/O  page,  it 
must  not  exceed  this  12K-word  limit.  If  it  does,  TKB  uses  APR  7  to 
map  the  task  instead  of  the  I/O  page. 

When  you  specify  an  argument  of  5,  there  will  be  8K  words  of  address 
space  between  the  beginning  of  the  ta^k  and  the  start  of  the  mapping 
for  the  I/O  page.  In  this  case,  the  task  must  not  be  greater  than  8K 
words  if  it  expects  to  access  the  I/O  page. 
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Figure    6-1      Privileged    Task   Mapping 
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Figure    6-2      Mapping    for    /PR:4    and    /PR:5 


ZKt32»y 


When  a  task  overlaps  the  I/O  page,  TKB  does  not  gener^t"  an  error 
message.  Before  TKB  generates  an  error  message,  a  task  designated  to 
be  mapped  with  APR  4  must  be  greater  than  16K  words;  a  task 
designated  to  be  mapped  with  APR  5  must  be  greater  than  12K  words. 
Only  when  you  install  a  task  that  overlaps  the  I/O  page  does  INSTALL 
generate  the  following  message: 

INS — WARNING--PRIVILEGED  TASK  NOT  MAPPED  TO  THE  I/O  PAGE 

While  this  is  not  a  fatal  error  message,  you  should  consider  the 
condition  to  be  fatal  if  you  expect  your  task  to  access  the  I/O  page. 

Vou  can  use  the  /-IP  switch  to  inform  TKB  that  the  task  is  purposely 
over  12K  and  does  not  need  to  be  mapped  to  the  I/O  page. 


without   interruptions   or   fear  of  the  data  being  changed  while  it  is 
being  accessed. 


6.6   /PR:0  PRIVILEGED  TASK 

Using  the  /PR:0  switch  causes  TKB  to  build  the  task  in  the  same  way  as 
any  other  task.  Virtucl  address  space  begins  at  virtual  address  0  and 
extends  upwards  as  far  as  32K  minus  32  words.  This  task  cannot  access 
the  Executive  routines  and  system  data  structures  or  directly  access 
the  I/O  page  because  tho  Task  Builder  has  not  reserved  APRs  for  these 
purposes . 
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Thoc*  at*  bclvantagoa  to  ualng  a  /PR:0  task  and  having  it  mappad   into 
APR  0.  A  /PR:0  taak  cant 

nypaas  file  protection. 

Use  the  alter  priority  (ALTP$)  directive. 

Issue  any  directive  that  has  a  target  task. 

Specify  a  device  name  in  spawn  directives. 

Write  logical  block  I/O  to  a  physically  mounted  volume, 
regardless  of  who  issued  the  Mount  or  Allocate  command.  For 
example,  the  V  R  task  is  a  /PR:0  task  and  writes  to  mounted 
volumes  during  the  SYSGEN  process.  However,  this  advantage 
can  be  hazardous  for  obvious  reasons. 


A  /PR:0  task  runs  in  user  state  and  cannot  switch  to  system  state. 
Also,  a  /PR:0  task  is  not  mapped  to  the  Executive.  If  you  want  to 
write  a  privileged  task  that  does  I/O  processing,  it  is  advantageous 
to  use  the  /PR:0  switch  for  your  task  because  there  is  less  chance  of 
corrupting  the  Executive  or  system  code  and  data. 


6.7   /PR: 4  PRIVILEGED  TASK 


If  you  want  your  pr 

and  your  Executive 

line.   If  you  speci 

the   I/O   page   and 

part  of  your  task's 

used   only   if   you 
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fy  /PR:4  for  you 
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map  to 
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use  the 

/PR: 

r  task. 

TKB 
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gh  3 
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The 

ze   is 

16K  0 

your  task  i 

TKB   a 

ppl  ie 

wi  thin 

the 

occurs 

whet 

Executive  and  I/O  page, 
4  switch  in  TKB  command 
reserves  APR  7  tc  map 
to  map  the  Executive  as 

/PR:4  switch  can  be 
r  less,  because  the  16K 
s  assigned  mapping  that 
s  a  bias  of  100000  (16K 

task.  This  specific 
her  the  task  is  in  user 


Up  to  12K  words  of  virtual  address  space  are  pos.sible  in  a  /PK:4  task. 
The  beginning  of  the  task  marks  the  end  of  the  Executive  code.  If  the 
task  is  12K  words  in  size,  the  end  of  the  task  mar'<s  the  start  of  the 
I/O  page.  If  the  task  is  going  to  access  the  I/O  page  through  APR  7, 
the  task  cannot  exceed  the  12K  limit.  If  the  task  doen  exceed  he 
limit,  TKB  is  forced  to  assign  APR  7  to  the  task  code.  Wlien  building 
the  task,  TKB  does  not  give  you  an  error  message  if  your  task  excteds 
».u„  t-,u    i;_it    However,  when  you  install  the  task,  INSTALL  sends  you 


the   12K  limit 

the  following  message 


"INS 


WAPHNG  —  PRIVILEGED  TASK  NOT  MAPPED  TO  THE  I/O  PAGE" 


6.8   /p->:5  PRIVILEGED  TASK 

If  you  want  your  privileged  task  to  map  to  the  Executive  and  I/O  page, 
and  your  Executive  is  between  16K  and  20K,  l  -.e  the  /PR:5  switch  in  TKB 
command  line.  If  you  specify  /PR:5  for  you'  ask,  TKB  reserves  APR  7 
to  map  the  I/O  page  and  reserves  APRs  C  throug  4  to  map  the  Executive 
as  part  of  your  task's  virtual  address  space.  The  /PR:5  switch  can  be 
used  only  if  your  Executive  size  is  between  I6K  and  20K,  because  the 
20K  Executive  uses  APRs  0  through  4  and  your  task  is  assigned  APR  5. 
(APR  5  may  be  used  if  the  Executive  is  less  than  16K,  but  this  wastes 
virtual  address  space.)  Therefore,  TKB  applies  a  bias  of  120000   (20K) 
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to  all  virtual  addresses  *;ithin  the  task.   This   specific   mapping   of 
APRS   0   through   5  and  7  occurs  whether  the  task  is  in  user  or  system 


state 


NOTE 


6.9   EXAMPLE  6-1:   BUILDING  A  PRIVILEGED  TASK  TO  EXAMINE  UNIT  CONTROL  BLOCKS 

The  MACRO-11  source  program  PRIVEX.MAC  in  Example  6-1  illustrates  one 
possible  use  of  a  privileged  task. 

NOTE 

The  nature  of  a  privileged  task  is  such 
that  you  must  have  a  working  knowledge 
of  system  concepts  to  understand  its 
operation  or  to  write  one.  If  this 
example  deals  with  Executive  functions 
th^t  are  unfamiliar  to  you,  you  may 
pr  fer  to  skip  this  section  and  return 
to  it  at  a  later  time. 

If  you  assemble,  build,  and  install  PRIVEX  into  your  system,  it  will 
scan  the  system  device  tables  and  examine  the  UCBs  of  all  nonpseudo 
devices  on  your  system.  It  will  determine  whether  each  device  is 
attached  by  a  task  and  print  on  your  term'nal  the  names  of  all 
attached  devices  on  your  system  with  the  name  of  each  attached 
program. 
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PRIVEX  accesses  two  Executive  routines:  $SWSTK  (switch  stack)  and 
$SCDVT  (scan  device  tables).  The  routine  $SWSTK  switches  the 
processor  to  system  state  (kernel  mode).  This  switch  to  system  state 
is  necessary  because  it  inhibits  all  other  processes  from  modifying 
the  Executive  data  structures  until  PRIVEX  is  finished  with  them.  The 
double  semicolons  (;;)  indicate  the  portion  of  the  task  that  is 
running  in  system  state. 

The  routine  $SCDVT  performs  the  actual  scanning  of  the  device  tables. 
It  returns  to  PRIVEX  each  time  it  accesses  a  new  UCB. 

PRIVEX  also  calls  the  system  library  routine  $EDMSG  (edit  message)  to 
format  the  data  it  has  retrieved  from  the  device  tables.  Tnis  routine 
is  documented  in  the  IAS/RSX-11  System  Library  Routines  Reference 
Manual. 


Example  6-1,  Part  1   Source  Code  for  PRIVEX 


MACRO   LIBRARY  CALLS 
.TITLE  PRIVEX 
.MCALL   ALUN$C,EXIT$S,QIOW$S 

LOCAL  DATA 

.NLIST   BEX 


ATTME3: 

.ASCIZ 

BUFMES: 

.ASCIZ 

•  LIST 

QIOBUF: 

.BLKB 

.EVEN 

/%2A'4P:  IS  ATTACHED  BY  %2R/ 

/BUFFER  OVERFLOW/ 

BEX 

132. 


JMESSAGE  OUTPUT  BUFFER 


BUFFER  INTO  WHICH  INFORMATION  IS  STORED  AT  SYSTEM  STATE  FOR 
PRINTING  AT  USER  STATE.   AN  ENTRY  IS  FOUR  WORDS  LONG: 


ADDRESS  IN  DCB  OF  THE  TWO  ASCII  CHARACTER  DEVICE  NAME 
BINARY  UNIT  NUMBER 
FIRST  RAD50  WORD  OF  NAME  OF  ATTACHED  TASK 
SECOND  RAD50  WORD  OF  NAME  OF  ATTACHED  TASK 

THE  BUFFER  IS  TEHMINATED  BY  A 

0   =  ALL  UNITS  IN  THE  SYSTEM  HAVE  BEEN  EXAMINED 

-1  =  THE  BUFFER  WAS  FILLED  BEFORE  ALL  UNITS  COULD  BE  EXAMINED 


BUFFER:  .BLKW   4*200. +1 
BUFEND=.-2 


;ADDRESS  OF  LAST  WORD  OF  BUFFER 


(continued  on  next  page) 
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Example  6-1,  Part  l(Co-  •.)   Source  Code  for  PRIVEX 


START: 


MOV 

♦BUFFER, R2 

CLR 

(R2) 

CLR 

Rl 

;GET  ADDRESS  OF  INFORMATION  BUFFER 
;ASSUME  NO  UNITS  ARE  ATTACHED 
; INITIALIZE  CURRENT  DCB  ADDRESS 


"CALL  $SWSTK, FORMAT"  SWITCHES  TO  SYSTEM  STATE.   ALL  REGISTERS 
ARE  PRESERVED  ACROSS  THE  TRANSITION  FROM  USER  MODE  TO  KERNEL 
MODE.   BEING  IN  SYSTEM  STATE  LOCKS  OTHER  PROCESSFS  OUT  OF  THE 
EXECUTIVE  (GUARANTEES  THAT  THE  DATA  BEING  EXAMINED  WILL  NOT 
CHANGE  WHILE  IT  IS  BEING  EXAMINED) .   A  "RETURN"  WILL  GIVE 
CONTROL  TO  "FORMAT"  AND  WILL  RESTORE  THE  CONTENTS  OF  THE 
REGISTERS  TO  THEIR  VALUES  BEFORE  THE  "CALL  $SWSTK". 


20$: 


CALL 
MOV 

C^LL 

BCS 


$SWSTK, FORMAT 
#$SCDVT,- (SP) 

@(SP)  + 

100$ 


SWITCH  TO  SYSTEM  STATE 

;GET  ADDRESS  OF  SCAN  DEVICE  TABLES 

; COROUTINE 

;GET  NEXT  NONPSEUDO  DEVICE  UCB 

;   ADDRESS 

;IF  CS  NO  MORE  UCBS 


AT  THIS  POINT: 

R3  -  ADDRESS  OF  THE  DEVICE  CONTROL  BLOCK 

R4  -  ADDRESS  OF  THE  STATUS  CONTROL  BLOCK 

;         R5  -  ADDRESS  OF  THE  UNIT  CONTROL  BLOCK 

; 


CMP  R1,R3 

BEQ  40$ 

MOV  R3,R1 

CLR  RO 

BISB  D.ONITfRS) ,R0 

40$:     MOV  U.ATT(R5),R4 

BEQ  60$ 

CMP  #BUFEND,R2 

BLOS  80$ 

ADD  #D.NAM,R3 

MOV  R3,(R2)+ 

MOV  R0,(R2)+ 

MOV  T.NAM(R4) , (R2)+ 

MOV  T.NAM+2(R4) , (R2)+ 

CLR  {R2) 

60$:     INC  RO 

BR  20$ 

80$:     CALL  @(SP)+ 

BCC  80$ 

COM  (R2) 
100$:    RETURN 


IS  THIS  A  NEW  DCB? 

IF  EQ  NO 

REMEMBER  THIS  DCB 

FORM  LOWEST  UNIT  NUMBER  ON 

THIS  DCB 
IS  A  TASK  ATTACHED? 
IF  EQ  NO 

IF  NE  R4  IS  TCB  ADDRESS 
ANY  MORE  ROOM  IN  BUFFER? 
IF  LOS  NO 

FORM  ADDRESS  OF  DEVICE  NAME 
SAVE  IT  IN  BUFFER 
SAVE  UNIT  NUMBER 
SAVE  NAME  OF  ATTACHED  TASK 

I  } 

ASSUME  NO  MORE  ATTACHED  UNITS 
INCREMENT  UNIT  NUMBER 

GET  $SCDVT  TO  CLEAN  OFF  STACK 

SHOW  BUFFER  OVERFLOW 

RETURN  TO  USER  STATE  AT  FORMAT 


, ENABL   LSB 


FORMAT:  TST 
BEQ 
CMP 
BNE 
MOV 
CALL 

EXIT:    EXIT$S 


(R2) 

EXIT 

#-l,(R2) 

40$ 

#BUFMES,R1 

PRINT 


;ANY  MORE  INFORMATION  IN  BUFFER? 

; I F  EQ  NO 

;OVERFLOWFD  BUFFER? 

;IF  NE  NO 

;GET  ADDRT.SS  OF  OVERFLOW  MESSAGE 

;PRINT  IT 


(continued  on  next  page) 
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Example  6-1,  Part  l(Cont.)   Source  Code  for  PRIVEX 


40$:     MOV  #ATTMES,R1 

CALL  PRINT 

BR  FORMAT 

.DSABL  LSB 


;GET  ADDRESS  OF  TEMPLATE 

;FORMAT  AND  PRINT  THE  INFORMATION 

; 


PRINT  -  FORMAT  AND  PRINT  A  MESSAGE 


INPUTS; 


I 


Rl  -  ADDRESS  OF  AN  $EDMSG  INPUT  STRING 
R2  -  ADDRESS  OF  AN  $EDMSG  PARAMETER  BLOCK 


OUTPUTS: 

R2  -  ADDRESS  OF  NEXT  PARAMETER  IN  THE  $EDMSG  PARAMETER  BLOCK 
;        RO,  Rl,  R3,  R4  ARE  DESTROYED 
;        R5  IS  PRESERVED 


PRINT:   MOV      #QIOBUF,R0        ;CET  ADDRESS  OF  OUTPUT  BUFFER 
MOV      R0,R3  ;SAVE  FOR  QIOW$S 

CALL     $EDMSG  ; FORMAT  MESSAGE  INTO  OUTPUT  BUFFER 


REMOVE  LEADING  ZEROS  FROM  UNIT  NUMBER 


20$; 


40$: 


MOV 

R3,R0 

TST 

(R0)  + 

MOV 

R0,R4 

DEC 

Rl 

CMPB 

#'0, (R0)+ 

BEQ 

20$ 

INC 

Rl 

CMPB 

#':,-(R0) 

BNE 

40$ 

MOVB 

#'0,(R4)+ 

INC 

Rl 

MOVB 

(R0)+,(R4)+ 

BNE 

40$ 

POINT  AT  OUTPUT  BUFFER 
INCREMENT  BY  TWO  (POINT  PAST 

DEVICE  NAME) 
REMEMBER  THIS  SPOT 
ASSUME  NiiXT  BYTE  IS  A  LEADING  ZERO 

(REDUCE  LENGTH  OF  MESSAGE) 
IS  IT? 

IF  EQ  YES  ~  IGNORE  IT 
COUNTERACT  TOO  MUCH  DECREMENTING 
WAS  THE  BYTE  A  COLON  (WAS  THE  UNIT 

NUMBER  ZERO)? 
IF  NE  NO 

ADD  A  ZERO  UNIT  NUMBER 
INCREASE  LENGTH  OF  MESSAGE 
TACK  ON  REST  OF  MESSAGE 
IF  NE  NOT  DONE 


PRINT  THE  MESSAGE  ON  LUN  "OUTLUN"  (DEFINED  BY  THE  TASK  BUILD  FILE) 
AND  WAIT  USING  EVENT  FLAG  1 


QIOW$S   #I0.WVB,#0UTLUN,#1, ,, ,R3,R1,#'  >> 

RETURN 

.END     START 


PRIVEX. MAC  shoulJ  be  assembled  with  the   following   assembler   command 
string: 

MAC>PRIVEX,PRIVEX/-SP  =  DRO:  [1,1]  EXEMC/Mt,,  [  11,  10]  k  •MC/PA:  1 ,  DR2  :  (  30  3  ,  1  ]  PRIVEX 

The  file  EXEMC  is  the  Executive  macro  library  and  the   file   RSXMC   is 

the   Executive  prefix   file.   The  switches  used  in  the  command  string 

are   described  in   the   IAS/RSX-11   MACRO- 11   Programmer 's   Reference 
Manual. 
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The  Task  Builder  conunand  sequence  for  PRIVEX  is  as  follows 


>TKB 

TKB>  PRI 
TKB>  DRO 
TKB>  / 
Enter  Op 
TKB>  UNI 


VEX/PR:  '5,  PRIVEX/'-SP=PRIVEX 

:  [3,54  1  RSXllM.STB,ij.<0:  [1,1]  EX  EL  IB/LB 


TKB> 
TKB> 
TKB> 
> 


GBL 
ASG 

V 


tions  : 

TS=1 

nEF=OUTLUN:l 
TIO:  1 


;DEFINE  NUMBER  OF  LUNS 

;DEPINE  LUN  ON  WHICH  TO  PRINT  MESSAGES 

;ASSIGN  LUN  TO  DEVICE 


This  command  sequence  directs  TKB  to  build  PRIVEX  as  a  privileged  task 
and  to  add  a  bias  of  120000  to  all  locations  within  it.  APR  5  was 
chosen  in  this  example  because  the  Executive  in  the  system  on  which 
this  example  was  originally  built  is  20K  words  long.  Tf  he  Executive 
in  your  system  is  16K  words  or  less,  you  can  use  /PR:4  when  you  build 
the  task. 

In  the  options  section  of  the  TKB  command  sequence,  the  UNITS=1  option 
specifies  that  PRIVEX  will  use  only  one  logical  unit.  The 
GBLDEF=0UTLUN:1  option  defines  the  symbol  OUTLUN  as  being  equal  to  1, 
and  the  ASG=TI0:1  option  associates  device  TIO:   with  logical  unit  1. 

The  TKB  map  for  PRIVEX  is  shown  in  Example  6-1,  Part  2.  The  GLOBAL 
SYMBOL  SECTION  has  been  shortened  to  save  space.  Note  that  the  tasK's 
address  limits  begin  at  virtual  address  120000.  Figure  6-3 
illustrates  how  TKB  allocates  virtual  address  space  for  the  program. 

Example  6-1,  Part  2   Task  Builder  Map  for  PRIVEX 


PRIVEX. TSK;1 


Memory   allocation   map    TKB   M40.10 
7-OCT-82         13:26 


Page    1 


Partition   name 
Identification 
Task      UIC 
Stack  limits 

PRG    xfr    address 
Task    attributes 
Total    address    windows 
Task      image      size 
Task    address    limits 
R-W  disk    blk    limits 


GEN 

01 

[303,11 

1?"230  121227  001000  00512. 

124610 

PR 

1. 

1920.  words 

120000  127323 

0000"2  000011  000010  00008, 


Root  segment : PRIVEX 


R/W  mem  limits  : 
Disk  blk  limits: 


120000  127323  007324  03796. 
000002  000011  000010  00008. 


(continued  on  next  page) 


6-10 


PRIVILEGED    TASKS 


Example    6-1,    Part    2    (Cont.)       Task    Builder    Map    for    PRIVEX 


Memory   allocation   synopsis; 
Sect  ion 


Title 


Ident 


.  BLK.  :  (RW,  I,LCL,REL,CON)  121230  005746  03046. 

121230  003656  01966.   PRIVEX  01 
$SRESL:  (RO,I,LCL,REL,CON)  127176  0001.14  00084. 


File 


PRIVEX. OBJ; 2 


Global    symbols: 

AS. DEL  000001 
D.VOUT  000004 
AS. EXT  000004 
D.VPWF    000006 


BT.OAB  000002 
F.NWAC  000034 
B.DIR  000026 
F.SCHA    000015 


DV.SDI  000020 
lE.DAA  177770 
DV.SQD  000040 
lE.DNA    177771 


D.RS81     177657 
D.RS83    177655 


SPDVTA    020000 
$YHCTB    022674 


$REMOV    054044 
.TT14      U23770 


SSGFFR    020652 


STICLR    041032 


Task    builder    statistics: 

Total    work    file    references:       2f0535. 
Work      file      reads:    0. 
Work      file  writes:    0. 
Size    of    core    pool; 
Size    of   work    f i le: 


13486,       words     (52.       P/'GES) 
12032.      words    (47.       PAGES) 


Elapsed    time : 00 : 00  :  51 


APR  7- 


APR  6 


APR  5- 


APR  4 


APR  3 


APR  2 


APR  1 


APR  0 


I/O  PAGE 


UNUSED 


-VIRTUAL  160000 


PRIVEX.  TSK 


EXECUTIVE 


VIRTUAL  127147   ^ 
VIRTUAL  120000  I 


TASK  ADDRESS  LIMITS 


VIRTUALO 


Figure  6-3   Allocation  of  Virtual  Address  Space  for  PRIVEX 
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■  -'"--•■■—--—"   CHAPTER  7   ■ -'-'— ^' 

USER-MODE  I-  AND  D-SPACE  (RSX-11M-PLU3  ONLY) 


This  chapter  discusses  the  Task  Builder's  ability  to  divide  a  user 
task  into  instruction  and  data  space  (I-  and  D-space) .  A  series  of 
figures  and  text  explain  task  mapping  and  the  use  of  task  windows  in 
an  RSX-llM-FuUS  system  with  an  I-  and  D-space  task.  In  the  text, 
comparisons  are  made  between  conventional  casks  and  I-  and  D-space 
tasks.  A  conventional  task  is  one  that  does  not  separately  map 
instruction  space  and  data  space. 

The  I-  and   D-space   feature   is   an   RSX-llM-PLUS  system  generation 

option.   The  feature  is  available  only  on  specific  processor  hardware. 

Conventional  tasks  can  be  run  in  an  I-  and  D-space  system,  but   an   I- 

and  D-space  task  cannot  run  in  a  system  that  does  not  have  the  option 
specified . 


7.1   USER  TASK  DATA  SPACE  DEFINED 

User  task  data  space  is  that  s;iace  that  contains  data  and  which  the 
user  task  accesses  through  D-space  APRs.  The  function  of  I-  and 
D-space  allows  a  total  of  16  APRs  to  map  your  ta^k:  8  APRs  i':or  data 
space  and  8  APRs  for  instruction  space.  If  your  task  uses  both  I-  and 
D-space  to  its  maximum  capacity,  it  can  contain  64K  words  of  virtual 
address  space.  In  addition  to  both  I-  and  D-spac-;,  if  your  task  links 
to  a  32K  word  supervisor-mode  library,  it  can  contain  96K  words  of 
virtual  address  space. 

To  separate  the  data  and  instructions,  your  task  can  use  PSECTs  td 
contain  the  data  or  instructions.  Also,  your  task  can  use  the  CRAW$ 
and  CRRG$  directives  to  dynamically  create  and  map  to  data-space 
regions.  See  the  RSX-llM/M-PLUS  Executive  Reference  Manual  for  the 
use  of  these  directives. 

Conventional  tasks  and  tasks  that  separate  instruction  space  and  data 
space  differ  in  only  a  few  areas  of  interest.  The  next  sections^ 
discuss  these  areas. 


7.2   I-  AND  D-SPACE  TASK  IDENTIFICATION 

Two  fields  denote  an  I-  and  D-space  task.  In  the  task  header,  the 
byte  that  has  the  offset  H.DMAP  identifies  the  task  D-space  mapping 
mask.  In  the  Task  Control  Block  (TCB) ,  the  T4.DSP  bit  in  the  fourth 
task  status  word  identifies  the  I-  and  D-space  task  to  the  system. 

The  system  task  leader  or  the  VMR  FIX  command  initializes  these  two 
fields  at  the  time  the  task  is  loaded.  Therefore,  tasks  built  on  a 
system  other  than  an  I-  and  C-space  system  may  be  run  without 
rebuilding  on  an  RSX-llM-PLUS  system  that  supports  I-  and  D-space. 
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The  I-  and  D-space  task  is  one  in  which  TKB  separates  the  data  areas 
and  instructions.  In  this  task,  data  areas  should  be  defined  by  the 
MACRO-11  .PSECT  directive  that  haa  the  data  attribute.  Similarly,  the 
. PSECT  directive  with  the  "I"  attribute  defines  instruction  areas. 


7.3   COMPARISCN  OF  CONVENTIONAL  TASKS  AND  I-  AND  D-SPACE  TASKS 

A  conventional  task  operating  in  user  mode  can  contain  32Kword8  of 
virtual  address  space  and  access  approximately  32Kwords  of  physical 
memory.  However,  a  task  using  both  I-  and  D-space  APRs  can  contain 
64Kwords  of  virtual  address  space  and  access  approximately  64Kword8  of 
memory. 

The  conventional  task  in  an  I-  and  D-space  system  uses  both  sets  of 
APRS.  However,  the  relocation  addresses  in  both  1-space  and  D-space 
APRS  are  identical.  Also,  the  task  windows  refer  to  I-space  APRs  in  a 
task  that  does  not  use  D-space. 

An  I-  and  D-space  task  can  use  separately  both  I-  and  D-space  APRs; 
that  is,  APRS  used  in  this  way  are  not  overmanped.  Because?  of  this, 
the  task  can  use  eight  D-space  APRs  to  access  and  use  data,  and  eight 
I-space  APRs  to  access  and  execute  instructions.  Using  16  APRs  allows 
the  I-  and  D-space  task  to  access  a  total  of  64Kwords  ot  physical 
memory  at  one  time. 

Table  7-1  contains  a  brief  mapping  summary  of  the  combinations  of  I- 
and  D-space  tasks,  I-  and  D-space  systems,  and  the  APR  mapping  that 
occurs . 


Table  7-1 
Mapping  Comparison  Summary 


I/D      I/D 
Task    System 


Mapping  Summary 


No      ¥*s      I-space  APRs  and  D-space  APRs  contain   the   same 
relocation  addresses. 


No       No 

Yes     Yes 


I-space  APRS  contain  relocation. 

I-space  APRS  map   instruction   space. 
APRS  map  data  space. 


D-space 


Yes 


No 


Not  possible. 


7,4   CONVENTIONAL  TASK  MAPPING 

Conventional  tasks   map   their   virtual   addresses  to   their   logical 

addresses   through   both   I-space  and  D-space  APRs.  That  is,  TKB  does 

not  separate  instruction  space  or   data   space   nor  does  the   system 

differentiate   the   spaces   except   by  the  logic  inherent  in  the  task. 

Therefore,  the  task  must  map  to  its  logical  address  space  by  both  sets 
of  APRs,  which  are  overmapped. 


Figure  7-1  shows  an  8K  conventional  task  linked  to  an  8K  region  that 
mats  to  its  logical  address  space  through  both  D-space  and  i-3pace 
APR*i  in  an  I-  and  D-space  system. 


# 
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Figure  7-1   Conventional  Task  Linked  to  a  Region  in  an 
I-  and  D-Space  System 


7.5   I-  AND  D-SPACE  TASK  MAPPING 

Figure  7-2  shows  an  8K  I-  and  D-space  task.  TKB  separated  the  data 
and  instructions  in  this  task.  Because  of  the  way  TKB  processes  task 
space,  the  task  header  must  physically  reside  at  the  beginning  of  the 
task  in  I-space.  TKB  puts  the  header  that  the  Executive  uses  for  task 
control  in  D-space.  Also,  the  task's  stack  is  in  D-space.  If  the 
task  is  to  have  an  external  header  (under  control  of  the  /XH  switch) , 
the  Executive  copies  the  header  in  D-space  and  puts  it  into  the 
contiguous  space  immediately  before  the  task's  I-space  in  memory.  For 
more  details,  see  Figure  B-4,  Image  on  Disk  of  Overlaid  I-  and  D-Space 
Task,  in  Appendix  B. 


The  task  shown  uses  two  APRs  because  of  its  size  (8K) 
maps  the  task's  header  and  stack  and  part  of  D-space. 


D-space  APR 
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Figure  7-2   I-  and  D-space  Task  Mapping  in  an  I-  and  D-space  System 
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7.6   TASK  WINDOWS  IN  I-  AND  D-SPACE  TASKS 

TKB  uses  different  windows  to  map  various  portions  of  an  I-  and 
D-space  task.  Window  0  in  an  I-  and  D-space  task  cannot  be  used 
because  it  maps  the  root  in  I-space.  Similarly,  you  cannot  use  window 
1  because  it  maps  the  D-space  part  of  the  root.  The  root  of  the  task, 
which  TKB  divides  into  I-  and  D-space,  therefore  requires  two  windows. 
TKB  reserves  the  use  of  these  two  windows.  You  can  specify  up  to  14 
windows  for  a  task  that  uses  I-  and  D-space. 


7.7   SPECIFYING  DATA  SPACE  IN  YOUR  TASK 

You  design  an  I-  and  D-:.'pace  task  by  specifying  data  space  separately 
from  instruction  space.  Good  programming  practice  suggests  that  all 
data  areas  and  buffers  should  be  located  in  adjacent  locations. 
Similarly,  all  instructions  should  be  located  in  adjacent  locations. 
However,  TKB  will  separate  and  agglomerate  instruction  and  data  space 
when  it  builds  the  task.  For  TKB  to  do  this,  you  must  use  a  method  of 
informing  it  about  which  statements  are  data  and  which  are 
instructions. 

For  the  MACRO-11  programmer,  the  way  to  separate  data  and  instructions 

is   to   use  the  MACRO-11  . PSECT  directive.  You  can  use  this  directive 

with  the  instruction  (I)  attribute  for  all  the   instruction   locations 

in   your   task's   code.    Also,   you   can  use  .PSECT  and  the  data  (D) 

attribute  for  all  the  data  locations.   You  must  define  a   data   .PSECT 

in   an   I-  and  D-space  task  even  though  no  actual  data  is  contained  in 

the  task.   In  this  case,  the  .PSECT  can  be  of  0  length. 

Note  that  I-  and  D-space  libraries  have  not  been  defined  and  are  not  a 
possible  configuration. 


7.8   OVERLAID  I-  AND  D-SPACE  TASKS 

Except  for  the  mapping  of  an  I-  and  D-space  task  and  the  location  of 
instructions  and  data,  the  I-  and  D-space  task  differs  little  from  a 
conventional  task.  However,  there  are  structural  differences  between 
a  non-overlaid  and  an  overlaid  I-  and  D-space  task.  By  comparing  the 
two  kinds  of  tasks,  the  figures  and  text  in  the  following  sections 
describe  the  non-overlaid  and  overlaid  I-  and  D-space  tasks.  Also, 
you  may  want  to  refer  to  the  description  of  overlaid  conventional 
tasks  in  Chapter  3. 

Figure  7-3  shows  a  simplified  disk  image  of  the  non-overlaid  I-  and 
D-space  task.  This  task  contains  four  I-space  PSECTs  and  four  D-space 
PSECTs.  TKB  collects  all  the  I-space  PSECTs  together  in  one  part  of 
the  root  and  all  the  D-space  PSECTs  in  another  part  of  the  root. 
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Figure  7-3   Simplified  Disl?  Image  of  a  Non-Overlaid  I-  and 

D-Space  Task 


Figure  7-4  shows  the  virtual  address  space  and  physical  memory 
occupied  by  an  overlaid  I-  and  D-space  task  called  lAND.  The  task  has 
a  total  physical  siz.e  of  160000  (octal)  bytes.  (You  may  want  to 
compare  Figure  7-4,  which  is  shown  next,  with  Figure  3-1  in  Chapter  3, 
which  shows  a  conventional  overlaid  task.)  The  instructions  and  data 
occupy  the  same  virtual  address  space  and  are  of  equal  physical  size; 
but  because  they  are  mapped  through  different  APRs,  they  occupy 
different  locations  in  physical  memory.  The  instructions  in  lAND 
occupy  four  PSECTs  that  have  the  instruction  (I)  attribute,  and  the 
data  in  lAND  occupy  four  PSECTs  that  have  the  data  (D)  attribute. 

In  Figure  7-4,  the  virtual  instruction  space  contains  PSECTs  A,  B,  and 
C,  which  are  those  that  contain  instructions,  and  ROOT  I,  which  is  the 
PSECT  in  the  root  that  contains  instructions.  TKB  places  the  unused 
header  in  I-space  part  of  the  root. 

Also,  in  Figure  7-4,  the  virtual  data  space  contains  PSECTs  D,  E,  and 
F,  which  are  those  that  contain  data,  and  ROOT  D,  which  is  the  PSECT 
in  the  root  that  contains  data.  TKB  places  the  task's  user  heai^er  in 
the  D-space  part  of  the  root. 


A3  an  overlaid  task,  a  possible  overlay  tree  may   look 
shown  in  Figure  7-5. 


like   the   one 


• 
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Figure    7-4      Overlaid    1-   ar.d    D-Spacs    Task   Virtual    Address    Space 
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Figure    7-5      Example   Overlay   Tree    for    Overlaid    I-    and   D-Space    Task    lAND 


The   accompanying    ODL   statement    for    this    task    is: 

.ROOT      ROOT-(OVRl,OVR2,OVR3) 

Notice  that  this  ODL  statement  is  not  different  from  any  overlaid  task 
with  this  tree  structure.  In  this  statement,  the  module  OVRl  contains 
the  instruction  PSECT  A  and  the  data  PSECT  E,  the  module  0VR2  contains 
the  instruction  PSECT  B  and  thu  data  PSFCT  F,  and  the  module  0VR3 
contains  the  instruction  PSECT  C  and  the  data  PSECT  G.  Also,  the  ROOT 
module  contains  the  instruction  PSECT  I  and  the  data  PSECT  D. 
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The  disk  image  of  this  overlaid  task,  shown 
the   instruction   and   data  PSECTs  in  ssyata 
illustrates   the  difference   between   disk 
non-overlaid   I-  and  D-space  task  diak  image 
the  disk  image  shown  in  Figure  7-3.   Notice 
segments   of   the   overlaid   lAND  task  into 
parts.   Any  autoload  vectors  generated  becau 
segments   are  also  included  in  the  segment  a 
for  I-  and  D-space  tasks  contain  two  parts: 
D-spjce   part.    TKB   places   each  part  with 
part  as  shown  in  Figure  7-6.   Autoload   vect 
tasks  are  discussed  in  detail  in  Chapter  4. 
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J^igure    7-6      Simplified    Disk    Image   of    Overlaid    I-    and    D-Space    Task    lAND 
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7.8.1  Autoload  Vectors  and  .STB  Files 

If  youi:  I-  and  D-space  task  links  to  an  overlaid  shared  region,  that 
region  must  have  been  buil*-  with  a  version  of  TKB  that  supports 
overlaid  I~  •'nd  D-space  tasks.  The  reason  for  this  iS  that  the  .STB 
files  for  overlaid  shared  regions  built  by  older  versions  of  TKB  do 
not  contain  the  ISD  records  that  are  needed  to  create  the  type  of 
autoload  vectors  that  I-  and  D-space  tasks  use. 

For  newer  versions  of  TKB  that  support  overlaid  I-  and  D-space  tasks, 
TKB  allocates  autoloadable  vectors  in  the  root  of  the  task  only  for 
those  entry  poincs  in  the  library  referenced  by  the  task.  To  create 
the  autoload  vectors,  TKB  uses  ISD  records  in  the  .STB  file  when 
linking  the  task  to  the  library  if  the  ISD  records  are  present. 
Therefore,  tasks  built  with  newer  versions  of  TKB  tend  to  be  smaller 
because  fewer  autoload  vectors  are  present. 

For  the  Fast  Task  Builder  (FTB)  and  older  versions  of  TKB  that  do  not 
support  I-  and  D-space  tasks,  each  autoload  vector  in  the  shared 
region's  .STB  file  is  allocated  in  the  root  of  the  task  being  linked 
to  the  region,  whether  or  not  the  entry  point  is  referenced  by  the 
task. 


NOTE 

Libraries  created  with  older  versions  of 
TKB  do  not  have  the  ISD  records  in  the 
.STB  file  that  newer  versions  of  TKB  use 
to  include  autoload  vectors  in  the  task 
from  the  .STB  file.  Therefore,  TKB  must 
create  autoload  vectors  for  every  entry 
point  in  the  library. 

If  you  are  using  one  of  these  older 
libraries  and  you  are  linking  an  I-  and 
D-space  task  to  it,  TKB  will  give  you 
the  fatal  error  message: 

"Module  module-name  contains 
incompatible  autoload  vectors" 

This  message   occurs   because  the   .STB 

file   contains    conventional  autoload 

vectors  that  are  not  usable  by  an  I-  and 
D-space  task. 

For  more  information  about  linking  shared  regions  to  I-  and  D-space 
tasks,  see  the  section  in  Chapter  5  entitled.  Autoload  Vectors  and 
.STB  Files  for  Overlaid  Shared  Regions. 


7.9   I-  AND  D-SPACE  TASK  MEMORY  ALLOCATION  AND  EXAMPLE  MAPS 

The  following  section  discusses  and  shows  the  differences  between  two 
versions  of  a  task  that  is  built  both  as  a  conventional  task  and  as  an 
I-  and  D-space  task.  The  conventional  task  is  called  MAIN.TSK  and  the 
I-   and   D-space   version   of   MAIN.TSK  is  called  MAINID.TSK.   Both  of 
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these  tastes  are  similar  to  but  not  the  same  as  the  task  called 
MAIN.TSK  shown  in  Chapter  5.  After  MAIN.TSK  was  coded,  built,  and  the 
map  printed,  MAIN.TSK  was  rebuilt  as  an  I-  and  D-space  task  to  create 
MAINID.TSK.  To  do  this,  the  /ID  switch  was  used  in  the  TKB  command 
line.   Both  versions  of  this  task  are  overlaid  and  link  to  a  library. 


7.9.1  Virtual  Memory  Allocation  for  MAIN.TSK 

MAIN.TSK  has  a  root  called  MAIN  and  three  overlay  segments  called 
INPUT,  CALC,  and  OUTPUT.  By  comparing  the  map  of  this  task  in  Example 
7-1  and  the  memory  allocation  diagram  in  Figure  7-7,  you  will  be  able 
to  determine  the  virtual  memory  space  allocation  and  structure  of  this 
task.  Note  that  the  overlay  segments  occupy  the  same  virtual  address 
space,  and  the  root  and  segments  are  mapped  in  both  I-space  and 
0-space. 
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Figure  7-7   Memory  Allocation  Diagram  for  MAIN.TSK 


7.9.2  Virtual  Memory  Allocation  for  MAINID.TSK 

MAINID.TSK  has  a  root  called  MAIN  and  three  overlay  segments.  In  this 
way  MAINID.TSK  resembles  MAIN.TSK.  However,  the  I-PSECTs  =ind  L  -PSECTs 
in  MAINID.TSK  are  separated  and  they  are  mapped  through  their 
respective  I-space  or  D-space  APRs.  Therefore,  MAINID.TSK  has  two 
virtual  address  spaces:  -n  I-space  and  a  D-space.  Figures  7-8  and 
7-9  show  the  mnmory  allocation  for  the  I-space  and  D-space  in 
MAINID.TSK. 

The  three  segments  INPUT,  CALC,  and  OUTPUT  occupy  the  same  virtual 
I-space,  because  these  three  segments  contain  instructions  and, 
therefore,  I-PSECTs.  However,  the  overlay  segment  OUTPUT  is  the  only 
segment  that  occupies  virtual  D-space  because  the  segments  INPUT  and 
CALC  do  not  contain  data  or  D-space  PSECTs.  Note  that  the  two  overlay 
S€igments  INPUT  and  CALC  have  no  D-space.  You  can  see  this  in  both 
Figure  7-9  and  the  map  in  Example  7-2.  The  map  in  Example  7-2  shows 
the  virtual  address  space  allocation  for  both  I-space  and  D-space. 
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An  I-  and  D- space  task  uses  more  virtual  memory  space  than  a 
conventional  task.  The  map  in  Example  7-2  shows  that  MAINID.TSK  uses 
1888.  words  of  space  as  opposed  to  the  1664.  words  used  by  MAIN.TSK. 
The  reasons  for  the  increase  in  size  of  MAINID.TSK  over  MAIW.TSK  are 
as  follows: 


•  An  I-  and  D-space  task  contains  an  unused  task  header. 

•  Autoload  vectors  in  an  I-  and  D-space  task  contain  two  more 
words  than  conventional  autoload  vectors.  PSECTs  $$ALVD  and 
$$ALVI  in  Example  7-2  contain  the  autoload  vectors.  You  can 
see  from  this  map  that  they  use  more  space  than  the  $$ALVC 
PSECT  in  MAIN.TSK,  which  contains  conventional  autoload 
vectors . 


•   The  segment  descriptors  in  an  overlaid 
contain  an  extension. 


and   D-space   task 


In  addition  to  these  reasons  for  the  increase  in  size  of  an   overlaid 

I-   and   D-space   task,  a  memory-resident  overlaid  I-  and  D-space  task 

would  be  even  larger  because  of  the  need  for   two   window  descriptors 
for  each  memory-resident  segment. 


004413 

003P63 
003007 

002714 
002713 


000000 


004413 

OUTPUT 

002714 

003263 

INPUT 

003007 

CALC 

002713 

MAIN 

000000 

Figure    7-8      Memory    Allocation    Diagram    for    MAINID.TSK    I-Space 


002513 


002414 
002413 


000000 


002513 
OUTPUT 

002414 


002413 


MAIN 


000000 


Figure    7-9      Memory   Allocation   Diagram   for   MAINID.TSK  D-Space 
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USER-MODE    I-   AND   D-SPACE    (RSX-llM-PLUS   ONLY) 


Example    7-i      Map    of    Overlaid    Task    MAIN.TSK 


MAIN.TSK;1        Memory   allocation  map      TKB  M40.10  Page    1 

20-OCT-82         10:08 


Task  name        : 

Partition   name    ! 

Identification    : 

Task      UIC  : 

Stack    limits! 

PRG  xfr  address; 

Total  address  windows:  3. 

Task   image   size   :  1664.  words 

Task  address  limits:  000000  006307 

R-W  disk  blk  limits:  000002  000012  000011  00009. 


...CBP 

GEN 

VOO.OO 

[240,1] 

000320  001317  001000  00512. 

002350 


MAIN.TSK;1  Overlay  description: 
Base    Top        Length 


000000  004513 

004514  005063 

004514  004607 

004514  006307 


004514  02380. 

000350  00232. 

000074  00060. 

001574  00892. 


MAIN 
INPUT 
CALC 
OUTPUT 


MAIN.TSK;!    Memory  allocation  map   TKB  M40.10      P ige  2 
MAIN  20-OCT-82    10:08 


Root  segment:  MAIN 


R/W  mem   limits:  000000  004513  004514  02380. 
Disk  blk  limits:  00000?  000006  000005  00005. 


Memory  allocation  synopsis: 

Section 

.  BLK.: (RH,I,LCL,REL,CON) 


COMl  . (RO,D,GBL,REL,CON) 

COM2  : (RW,D,GBL,REL,CON) 

COM3  : (RW,D,GBL,REL,CON) 

COM4  : (RW,D,GBL,REL,CON) 

CCM5  : (RW,D,GBL,REL,CON) 


001320  000466  00310. 
001320  000250  00168. 
001570  000216  00142. 
002006  000024  00020. 
002006  000024  00020. 
002032  000032  00026. 
002032  000032  00026. 
002064  000010  00008. 
002064  000010  00008. 
002074  000234  00156, 
002074  000234  00156. 
002330  000020  00016. 


Title  Ident  File 

EDDAT  03  SYSLIB.0LB;5 

CBTA  04.3  SYSLIB.0LB;5 

MAIN  VOO.OO  MAIN.0BJ;36 

MAIN  VOO.OO  MAIN.OBJ;26 

MAIN  VOO.OO  MAIN.OBJ;36 

MAIN  VOO.OO  MAIN.OBJ;36 

(continued  on  next  page) 
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Example  7-1  (Cont.)   Map  of  Overlaid  Task  MAIN.TSK 


LIBROT: (RW, I,GBL,REL,CON) 
MAIN  : (RO, I,LCL,REL,CON) 
$$ALER: (RO,I,LCL,REL,CON) 

S$ALVC: (RO, I,LCL,REL,CON) 


002330  000020  00016.  MAIN   VOO.OO  MAIN.OBJ;36 

000000  000140  00096. 

000000  000140  00096. 

002350  000142  00098. 

002350  000142  00098. 

002512  000024  00020. 

002512  000000  00000. 

002512  000024  00020.  ALERR 

002536  000070  00056. 


LIBROT  03.01   LIBFS0.STB;1 
MAIN    VOO.OO  MAIN.OBJ;36 


OVCTR 


15.03 
02.00 


SYSLIB.0LB;5 
SYSLIB.0LB;5 


Global  symbols; 

AADD    002556-R   N.DTDS  000020 
ARGBLK  002046-R   N.FAST  000013 


$CBDAT  001570-R   .FSRPT  000050 
$CBDMG  001576-R   . NALER  003354-R 


MAIN.TSK;!    Memory  allocation  map   TKB  M40.10      Page  4 
INPUT  20-OCT-82    10:08 


Segment:  INPUT 


R/W  mem   limits:  004514  005063  000350  00232. 
Disk  blk  limits:  000007  000007  000001  00001. 


Memory  allocation  synopsis! 

Section 

.  BLK. : (RW, I,LCL,REL,CON) 

INPUT  : (RO, I,LCL,REL,CON) 

$$ALVC: (RO, I ,LCL, REL,  CON) 


Title   Ident   File 


004514  000074  00060. 

004514  000074  00060.  CATB    03 

004610  000252  00170. 

004610  000252  00170.  INPUT   01 

005062  000000  00000. 


SySLIB.0LB;5 
INPUT. OBJ;32 


Global  symbols: 

INPUT   004610--R   $CDTB   004514-R   SCOTB   004522-R 


(continued  on  next  page) 


/ 
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USER-HODE    I-   ANL*   U-SPACE    (RSX-ilM-PLUS   ONLY) 


Example   7-1    (Cont.)      Map  of    Overlaid   Task    MAIN.TSK 


MAIN.TSK;!        Memory   allocation  map      TKB  M40.10  Page   5 

20-OCT-82         10:08 


***  Task  builder  statistica: 

Total  work  file  references:  13626. 

Work   file   rea<1s:  0. 

Work   file  writes:  0. 

Size  of  core  pool:  5198.  words  (20.  pages) 

Size  of  work  file:  4096.  words  (16.  pages) 

Elapsed  t ime :00 :00 : 19 


ExamplG  7-2   Map  of  Overlaid  I-  and  D-Space  Task  MAINID.TSK 


MAINID.TSK;1   Memory  allocation  map  TKB  M40.10      Page  1 

15-OCT-82    11:51 


Task    name 

Partition  nare  : 

Identification  ; 

Task   UIC 

Stack    limits: 

PRG  xfr  address; 

Task  attributes: 

Total  address  windows:  4. 

Task   im.ige   size   :  1184. 

704.  words,  D-Space 
Task  Address  limits:  000000  004413  I-Space 

000000  002513  D-Space 
R-W  disk  blk  limits:  000002  000014  000013  00011. 


.  . ,CBP 

GEN 

VOO.OO 

[240,1] 

000256  001255  001000  00512. 

0007*4 

ID 


words,  I -Space 


NAINID.TSK;1  Overlay  description: 
Base     Top        Length 


000000   002713   002714   01484.  I 
000000   002413   002414   01292.  D 


MAIN 


002714   003263   000350   00232.  I 
002414   002413   000000   00000.  D 


INPUT 


002714   003007   000074   00060.  I 
002414   002413   000000   00000.  D 


CALC 


002714   004413   001500   00832.  I 
002414   002513   000100   00064.  D 


OUTPUT 


(continued  on  next  page) 
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USER-MODE  I-  AND  D-SPACE  ( RSX-llM-PLUS  ONLY) 


Example  7-2  (Cont.)   Map  of  Overlaid  1-  and  D-Space  Task  MAINID.TSK 


MAINID.TSK;!   Memory  allocation  map   TKB  M40.10      Page  2 
MAIN  15-OCT-82    11:51 


•**  Root  segment:  MAIN 


R/W  mem   limits:  000000  002713  002714  01484.  I-Space 
000000  002413  002414  01292.  D-Space 


Disk  blk  limits: 


000002  000004  000003  00003,  I-Space 
000005  000007  000003  00003.  D-Space 


Memory  allocation  syn   sisi 

Section 

.  BLK. : (RW, I,LCL,PEL,CON) 

COMl  : (RO,D,GBL,REL,CON) 
COM2  : (RW,D,GBL,REL,CON) 
COM3  : (RW,D,GBL,REL,CON; 
COM4  : (RW,D,GBL,REL,CON) 
C0M5  : (RW,D,GBL,REL,CON) 
LIBROT: (RW, I ,GBL , kEL,CON) 
MAIN  :  (RO,  I,[,CL,REL,CON) 
$$ALER: (RO, I , LCL, REL.CON) 


S$ALVD: (RO,D,LCL,REL,CON) 
$$ALVI :  (RO,  I,LCL,REL,CON) 


Title   Ident   File 


000256 

0004b6 

00310. 

000256 

000250 

00168. 

EODAT 

03 

000526 

000216 

00142. 

CBTA 

04. 

3 

001256 

000024 

00020. 

001256 

000024 

00020. 

MAIN 

voo 

.00 

001302 

000032 

00026. 

001302 

000032 

00026. 

MAIN 

voo 

.00 

001334 

000010 

00008. 

001334 

000010 

00008. 

MAIN 

voo 

.00 

001344 

000234 

00156. 

001344 

000234 

00156. 

MAIN 

voo 

.00 

001600 

000020 

00016. 

001600 

000020 

00016. 

MAIN 

voo 

.00 

000000 

000140 

00096. 

000000 

000140 

00096. 

LIBROT 

03. 

01 

000744 

000142 

00098. 

000744 

000142 

00098. 

MAIN 

voo 

.00 

001106 

000024 

00020. 

001106 

onoooo 

00000. 

OVIDR 

Oi 

001106 

000024 

00020. 

ALERR 

02. 

00 

001620 

000034 

00028. 

001132 

000070 

00056. 

SYSL1B,OLB;10 
SYSLIB.OLb; 10 

MA  I  N.OB J; 34 

MA  I  N.OB J; 34 

MA  IN. OBJ; 34 

MA  I  N.OB J, -34 

MAIN. OBJ; 34 

LIBFS0.STB;1 

MAIN. OBJ; 34 

SYSLIB.OLB;10 
SYSLIB.OLB; 10 


Global  symbols: 

AADD    001152-R   N.DTDS  000020 
ARGBLK  001316-R   N . FAST  000013 


$CBDAT  000526-R   $TIM    000402-R 
$CBDMG  000534-R   SVEXT   000056 


MAINID.TSK; 1 
INPUT 


Memory  allocation  map   TKB  M40.10 
15-OCT-82    11:51 


Page  4 


(continued  en  next  pdg&) 
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USER-NODE  I-  AND  D-SPACE  (RSX-llM-PLOS  ONLY) 


Example  7-2  (Cont.)   Map  of  Overlaid  I-  and  D-Space  Task  MAINID.TSK 


***  Segment:  INPUT 


R/W  mem   limits:  002714  003263  000350  00232.  I-Space 

002414  002413  000000  00000.  D-Space 

Disk  blk  limits:  000010  000010  000001  00001.  I-Space 

000011  000011  000000  00000.  D-Space 


Memory  allocation  synopsis: 

Section 

.  BLK.  : (RW,I,LCL,REL,CON) 

INPUT  : (RO,I,LCL,REL,CON) 

$$ALVD: (RO,D,LCL,REL,CON) 
$$ALVI: (RO,I,LCL,REL,CON) 
$$RTS  :(RO,I,GBL,REL,OVR) 
$$SLVC: (RO,I,LCL,REL,CON) 


Title   Ident   File 


002714  000074  00060. 
002714  000074  00060. 
003010  000252  00170. 
003010  000252  00170. 
002414  000000  00000. 
003262  000000  00000. 
002710  000002  00002. 
003262  000000  00000. 


CATB 


03 


INPUT   01 


SYSLIB.OLD;10 
INPUT. OBJ;32 


Global  symbols: 

INPUT   003010-R   $CDTB   002714-R   SCOTS   002722-R 


MAINID.TSK;1 
CALC 


Memory  allocation  ma 
15-OCT-82   11 


TKB  M40.10 


Page  5 


***  Task  builder  statistics: 

Total  work  file  referetices:  13920. 

Work   file   reads:  0. 

Work   file  writes:  0. 

Size  of  core  pool:  5010.  words  (19.  pages) 

Size  of  work  file:  4096.  words  (16.  pages) 

Elapsed  time:00  t00:28  „,  ~  .r,.  -  • 


.^:-^:  irur,'-.   . //fM 


m 
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CHAPTER  8 
SOPBRVISOR-MOOB  LIBRARIES  (R5X~11M-PL0S  ONLY) 


A  supervisor-mode  library  is  a  resident  library  that  doubles  a  user 
task's  virtual  address  space  by  mapping  the  instruction  space  of  the 
processor's  supervisor  mode.  Supervisor-mode  libraries  are  available 
only  on  RSX-llN-PLl'S  systems  running  on  PDP-11/44S  and  PDP-11/708. 


8.1   INTRODUCTION 

A  call  from  witidn  a  user  task  to  a  subroutine  within  a 
supervisor-mode  library  causes  the  processor  to  switch  from  user  to 
supervisor  mode.  The  user  task  f  nsfers  control  to  a  mode-switching 
vector  that  TKB  includes  within  the  task.  The  mode-switching  vector 
performs  the  mode  switch  and  then  transfers  control  to  the  called 
subroutine  within  the  supervisor-mode  library.  The  library  routine 
executes  with  t^e  processor  in  supervisor  mode.  When  the  library 
routine  finishes  executing,  it  transfers  control  to  a  completion 
routine  within  the  library.  The  completion  routine  mode  switches  the 
processor  back  to  user  mode.  The  user  task  continues  executing  with 
the  processor  in  user  mode  at  the  return  address  on  the  stack.  This 
process  rerurs  whenever  the  user  task  calls  a  subroutine  in  the 
supervisor- raode  library. 


8.2   NODB-SWITCHING  VECTORS 

In  a  task  that  links  to  a  supervisor-mode  library,  TKB  includes  a 
4-word,  mode-switching  vector  in  the  user  task's  address  space  for 
each  entry  point  referenced  of  a  subroutine  in  the  library. 

The  following  shows  the  contents  of  a  mode-switching  vector: 

MOV  #COMPLETION-ROUTINE,-(SP) 

CSN  #SUPERVISOR~MODE-ROUTINE  ADDRESS 

NOTE 

When  mode  switching  from  user  to 
supervisor  mode,  all  registers  of  the 
referencing  task  are  preserved.  All 
condition  codes  in  the  PS  saved  on  the 
stack  are  cleared  and  must  be  restored 
by  the  completion  routine. 
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8.3   COMPLETION  ROUTINES 

After  the  subroutine  finibhes  executing,  its  RETURN  statement 
transfers  control  to  a  completion  routine  that  mode-switches  from  the 
supervisor  to  user  mode.  The  completion  routine  returns  program 
control  back  to  the  referencing  task  at  the  instruction  after  the  call 
to  the  subroutine.   There  are  two  completion  routines  in  SYSLIB: 

•  $CMPCS  restores  only  the  carry  bit  in  the  user-mode  PS. 

•  $CMPAL  restores  all  the  condition  code  bits  in   the   user-mode 
PS. 


8.4   RESTRICTIONS  ON  THE  CONTENTS  OF  SUPERVISOR-NODE  LIBRARIES 

The   following   restrictions  are   placed   on   the   contents   of   a 
supervisor-mode  library: 

•  Only  subroutines  using  the  form  JSR  PC,  x  should  be  used 
within  the  library. 

•  The  library  must  not  contain  subroutines  that  use  the  stack  to 
pass  parameters. 

•  If  both  the  library  and  the  referencing  task  link  to  a 
subroutine  from  SYSLIB,  then  the  entry  point  name  of  the 
subroutine  must  be  excluded  from  the  .STB  file  for  the 
library. 

•  Unless  you  include  the  MSDS$  directive  within  the  library,  the 
library  must  not  contain  data  of  any  kind  (even  R/0)  because 
the  user  supervisor  D-space  APRs  map  the  user  task  by  default. 
This  includes  user  data,  buffers,  I/O  status  blocks,  and 
directive  parameter  blocks  (only  the  $S  directive  form  can  be 
used,  because  the  DPS  for  this  form  is  pushed  onto  the  user 
stack  at  run  time) . 

Using  the  Map  Supervisor  D-space  Executive  Directive  (MSDS$) , 
the  library  can  map  data  within  the  instruction  space  of  the 
supervisor-mode  library  by  using  the  supervisor  D-space  APRs. 
The  directive  maps  specific  supervisor  D-space  APRs  to 
supervisor  instruction  space  by  copying  the  supervisor  I-space 
APRs  that  map  the  data  portion  of  the  library.  To  effectively 
contain  data  within  a  supervisor-mode  library,  you  must  know 
which  APRS  map  the  data  portions  of  your  task  and  library. 

NOTE 

You  cannot  use  MSDS$  to  map  supervisor 
D-space  APR  0.  Mapping  library  data  and 
the  user  task  simultaneously  should  be 
done  with  extreme  care.  Section  5.3.4.2 
of  the  RSX-llM/M-PLUS  Executive 
Reference  Manual  discusses  the  MSDS$ 
di  rective  in  detail.  .< 
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8.5   SUPERVISOR-MODE  LIBRARY  MAPPING 

Supervisor-mode  libraries  are  mapped  with  the  supervisor  I-space  APRs . 
Supervisor  D-space  APRs  can  map  the  user  task,  data  within  the 
library,  or  both  the  user  task  and  library  data  simultaneously.  They 
map  the  user  task  by  default. 

The  supervisor  D-space  APRs  can  be  mapped  differently  according  to 
whether  the  library  contains  data. 

Supervisor  D-space  APRs  are  copies  of  user  I-;3pace  APRs,  which  map  the 
entire  user  task.  This  gives  the  library  access  to  data  within  the 
user  task.   Figure  8-1  illustrates  this  mapping. 


8.5.1  Supervisor  Mode  Library  Data 

Libraries  that  contain  data  require  extremely  complicated  mapping  that 
may  overwrite  the  user  task  or  cause  the  task  to  fail. 

Supervisor  D-space  APRs  are  copies  of  user  1-space  APRs,  which  map  the 
entire  user  task.  For  I-  and  D-space  tasks,  the  supervisor  D-spaces 
APRS  are  copies  of  the  user  D-space  APRs.  Including  the  MSDS$ 
Executive  directive  (see  Section  8-4)  within  the  library  code  enables 
the  library  to  map  data  within  its  own  instruction  space.  The  user 
task  may  be  overm.ipped .  The  library  has  access  to  data  within  its 
instruction  space  and  to  data  in  the  user  task  that  is  not  overmapped 
by  the  MSDS$  directive. 

Figure  8-2  illustrates  this  mapping. 


8.5.2  Supervisor  Mode  Libraries  with  I-  and  D-Space  Tasks 


Figure  8-3  illustrates  the  mapping  of  an  I-  and  D-space  task  linked  to 
a  supervisor  mode  library. 
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Figure  8-1  Napping  of  a  24K  Conventional  Oser  Task  That  Links  to  a 

16K  Supervisor-Mode  Library 
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Figure  8-2   Mapping  of  a  20K  Conventional  User  Task  That  Links  to  a 
12K  Supervisor-Mode  Library  Containing  4K  of  Data 
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Figure  8-3   Mapping  of  a  40K  I-  and  D-Space  Task  That  Links 
to  an  8K  Supervisor-Mode  Library 
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8.6   BOILDING  AND  LINKING  TO  SUPERVISOR-MODE  LIBRARIES 

Building  and  linking  to  a  supervisor-mode  library  is  essentially  the 
same  as  building  and  linking  to  a  conventional  resident  library 
(discussed  in  Chapter  5).  When  you  build  a  supervisor-mode  library, 
you  suppress  the  header  by  attaching  /-HD  to  the  task  image  file. 
During  option  input,  you  suppress  v.he  stack  area  by  specifying 
STACKED.  You  specify  the  partition  in  which  the  library  is  to  reside 
and,  optionally,  the  base  address  and  length  of  the  library  with  the 
PAR  option. 


8.6.1   Relevant  TKB  Options 

Use  the  following   options   to   build   and   reference   supervisor-mode 
libraries : 


CMPRT 


Indicates  that  you  are  building 
supervisor-mode  library  and  specifies  the 
name  of  the  completion  routir.e. 


RESSUP  (SOPLIB) 


Indicates   that   your    task 
supervisor-mode  library. 


references 


GBLXCL 


Excludes  a  global  symbol  from  the   .STB   file 
of  the  supervisor-mode  library. 


These  options  are  discussed  briefly  below  and  are  fully  documented   in 
Chapter  11. 


8.6.2   Building  the  Library 

You  indicate  to  the  Task  Builder  that  you  are  building  a 
supervisor-mode  library  with  the  CMPRT  option.  The  argument  for  this 
option  identifies  the  entry  symbol  of  the  completion  routine.  When 
the  Task  Builder  processes  this  option,  it  places  the  completion 
routine  entry  point  in  the  library's  STB  file.  To  exclude  a  global 
symbol  from  the  library's  .STB  file,  you  specify  the  name  of  the 
global  symbol  as  the  argument  of  the  GBLXCL  option.  You  must  exclude 
from  the  .STB  file  of  a  supervisor-mode  library  any  symbol  defined  in 
the  library  that  represents  the  following: 


•   An  entry  point  to  a  subroutine  that  uses 
parameters 


the  stack   to  pass 


•   An  entry  point  to  a  subroutine  mapped  in  user 
referencing  user  task  calls 


mode  that  the 


8.6.3   Building  the  Referencing  Task 

When  you  build  a  task  that  references  a  supervisor-mode  library,  use 
the  RESSUP  option  if  you  are  referencing  a  user-owned,  supervisor-mode 
library  and  SUPLIB  if  you  are  referencing  a  system-owned, 
supervisor-mode  library.  (Like  the  RESLIB  and  LIBR  options  for 
linking  tr  conventional  libraries.  RESSUP  and  SUPLIB  are  functionally 
the  same.)  The  arguments  for  these  options  are: 


•   The  fileppec  (RE5SUP  ption)  or  name  (SUPLIB)  of 
to  be  referenced 


the   library 
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A  switch  that  tells  TKB  whether  to  use  system-supplied  vectors 
to  perform  mode  switching  from  user  to  supervisor  mode. 

For   position-independent   libL!iries,   the    first   available 
supervisor-mode  I-space  APR  that  you  want  to  map  the  library. 


8.6.4  Mode  Switching  Instruction 

Node  switching  occurs  with  a  new  instruction  available  on  the  11/44 
and  emulated  by  the  Executive  on  the  11/70.  Throughout  the  remainder 
cf  the  chapter,  supervisor-mode  libraries  are  referred  to  as  CSM 
(change  supervisor  mode)  libraries. 


8.7   CSM  LIBRARIES 

This  section  discusses  how  you  build  and  link  to  CSM  libraries.    It 

also   shows   an  extended   example   of   building   and  linking  to  a  CSM 

library  and  explains   the   contjxt-sw\tching   vectors  and   completion 
routines  for  CSM  libraries. 


8.7.1  Building  a  CSM  Library 

You  indicate  to  the  Task  Builder  that  you  are  buildiny  a  CSM  library 
by  specifying  the  name  of  the  completion  routine  as  the  argument  for 
the  CMPRT  option.  This  option  places  the  name  of  the  completion 
routine  into  the  library's  .STB  file.  Link  the  completion  routine, 
eil;her  $CMPAL  or  $cMPCS,  located  in  LB:  (1,2]  SYSLIB.OLB,  as  the  first 
input  file.  Although  the  completion  routines  are  located  in  SYSLIB 
(wh'ch  is  ordinarily  referenced  by  default),  yon  must  explicitly 
indicate  it  and  link  it  as  the  first  input  file.  You  must  also 
specify  in  the  PAR  option  a  0  base  for  the  partition  in  which  the 
library  will  reside.  These  two  steps  locate  the  completion  routine  at 
virtual  0  of  tht;  library's  virtual  address  sp-^e. 

You  specify  the  name  of  any  global  symbols  that  you  would  like  to 
exclude  from  the  library's  .STB  file  as  the  argument  to  the  GBLXCL 
option.  You  must  exclude  from  the  .STB  file  of  a  supervisor-mode 
library  any  symbol  defined  in  the  library  that  represents  the 
following: 

•  An  entry  point  to  a  subroutine  that  uses   the   stack   to   pass 
parameters 

•  An  entry  point  to  a  subroutine  mapped  in  user   mode   that   the 
referencing  user  task  calls 

A  sample  TKB  sequence  for  building  a  CSM  library  in  UFD  [301,55]  on 
SY:   follows: 

TKB>CSM/-HD/LI/PI ,CSM/MA,CSM= 

TKB>LB: [ [1,2] ) SYSLIB/LB:CMPAL,SY : ( [301,55] ]CSM 

TKB>/ 

Enter  Options: 

TKB>STACK=0 

TKB>PAR=GEN: 0:2000 

TKB>CMPRT=$CMPCS 

TKB>GBLXCL=$SAVAL 

TKB>// 
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The  library  is  built  without  a   header   or   stack,   like   all   shared 

regions.    It  is  position  independent  and  has  only  one  program  section 

named  .ABS.   The  /LI  switch   accomplishes   this,   eliminating  proaram 

section  name  conflicts  between  the  library  and  the  referencing  task. 

The  completion  routine  module  of  SYSLIB,  CMPAL,  is  specified  first  in 
the  input  line.  The  library  will  run  in  partition  GEN  at  0  and  is  not 
more  than  IK.  These  are  two  aspects  of  building  supervisor-mode 
libraries  specific  to  CSM  libraries:  the  completion  routine  must  be 
linked  first,  and  must  reside  at  virtual  0.  Why  the  CSM  library  must 
reside  at  virtual  0  is  discussed  in  Section  8.8.5. 

The  CMPRT  option  specifies  the  global  symbol  $CMPCS,  which  is  the 
entry  point  of  the  completion  routine.  Note  that  the  SYSLIB  module 
name  is  "CMPCS"  and  its  corresponding  global  symbol  is  "$CMPCS". 

The  GBLXCL  option  excludes  $SAVAL  from  the  library's  .STB  file  because 
the  user  task  must  reference  a  copy  of  $SAVAL  that  is  mapped  with  user 
mode  APRS. 


8.7.2  Linking  to  a  CSH  Library 

If  your  task  links  to  a  user-owned  CSM  library,  you  use  the  RESSUP 
option.  If  your  task  links  to  a  system-owned  CSM  library,  you  use  the 
SUPLIB  option.  These  options  tell  TKB  that  the  task  will  link  to  a 
supervisor-mode  library.   The  option  takes  up  to  three  arguments: 

•  The  filespec  (RESSUP  option)  or  name  (SUPLIB  option)  of  the 
library 

•  A  switch  that  tells  the  Task  Builder  whether  to  use 
system-supplied,  mode-switching  vectors 

•  For  position-independent  libraries,  an  APR  that  must  be  APR  0 
so  that  the  library's  completion  routine  :ls  mapped  at  virtual 
0. 

This  information  enables  the  Task  Builder  to  find  the  .STB  file  for 
the  CSM  library,  include  a  4-word,  mode-switching  vector  within  the 
user  task  for  each  call  to  a  subroutine  within  the  library,  and 
correctly  map  the  library  at  virtual  0  in  the  library  image. 

The  following  sample  task-build  command  sequence  builds  a  task  named 
REF,  which  references  the  library  SUPER  that  you  built  in  the  previous 
section: 

TKB>REF,P.EF=REF 

TKB>/ 

Enter    Options: 

TKB>RESSUP=SUPER/SV: 0 

TKB>// 

This  sequence  tells  TKB  to  include  in  the  logical  address  space  of  REP 
a  user-owned,  supervisor-mode  library  named  SUPER.  TKB  will  include  a 
4-word  mode  switching  vector  within  the  user  task  for  each  call  to  a 
subroutine  within  the  library.  The  CSM  library  is  position 
independent  and  will  be  mapped  with  APR  0. 
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8.7.3   Example  CSN  Library  and  Linking  Task 

This  example  shows  you  the  code,  maps,  and  TKB  command  sequences  for 
building  and  linking  to  a  CSM  library  that  contains  no  data  in  a 
system  not  having  user  data  space.  Example  8-1  shows  the  code  for  the 
library  SUPER,  and  Example  8-2  shows  its  accompanying  map.  Example 
8-3  shows  the  code  for  the  completion  routine  $CMPCS  that  is  linked  in 
to  SUPER  from  SYSLTB.  Example  8-4  shows  the  code  for  referencing  task 
TSUP,  and  Example  8-5  shows  its  accompanying  map. 

Example  8-1   Code  for  SUPER. MAC 


.TITLE 

SUPER 

.IDENT 

/Ol/ 

SORT: : 

CALL 

$SAVAL           ; 

TST 

(R5)+          ; 

NOV 

(R5)+,R0         ; 

MOV 

{R5)+,R4        ; 

NOV 

{R4),R4         ; 

BBQ 

405 

MOV 

R0,R5 

DEC 

R4 

10$: 

MOV 

R5,R0            ; 

'>f\fi   • 

MOV 

R4,R3            ; 

ZUs*  • 

TST 

(R0)+          ; 

CMP 

(R5),(R0)       ; 

BLB 

30$           ; 

MOV 

(R5),R2         ; 

MOV 

(R0),(R5)        ; 

MOV 

R2,(R0)          ; 

30$: 

DEC 

R3 

BGE 

20$            ; 

DEC 

R4             ; 

BLE 

40$            ; 

TST 

(R5)+          ; 

BR 

10$ 

40$: 

RETURN 

SEARCH: 

. 

CALL 

$SAVAL 

CMP 

#4,(R5)+         ; 

BNE 

20$            ; 

MOV 

(R5)+,R0         ; 

MOV 

(R5)+,R1        ; 

MOV 

(R5)+,R2         ; 

MOV 

(R2),R2         ; 

BEQ 

20$            ; 

MOV 

(R5),R5 

MOV 

R2,R3           ; 

10$: 

CMP 

(R0),(R1)+      ; 

BBQ 

30$             ; 

BMI 

20$            ; 

DEC 

R2             ; 

BNE 

10$            ; 

SAVE  ALL  REGISTERS 

SKIP  OVER  NUMBER  OF  ARGUMENTS 

GET  ADDRESS  OF  LIST 

GET  ADDRESS  OF  LENGTH  OF  LIST 

GET  LENGTH  OF  LIST 

IF  NO  ARGUMENTS 


COPY 

COPY  LENGTH  OF  LIST 

MOVE  POINTER  TO  NEXT  ITEM 
COMPARE  ITEMS 
IF  LE  IN  CORRECT  ORDER 
SWAP  ITEMS 


DECREMENT  LOOP  COUNT 

IF  NE  LOOP 

DECREMENT 

IF  EQ  SORT  COMPLETED 

GET  POINTER  TO  NEXT  ITEM  TO  BE  COMPARED 


SAVE  ALL  THE  REGISTERS 

FOUR  ARGUMENTS? 

IF  NE  NO 

GET  ADDRESS  OF  NUMBER  TO  LOCATE 

ADDRESS  OF  LIST  SEARCHING 

GET  ADDRESS  OF  LENGTH  OF  LIST 

GET  LENGTH  OF  LIST 

IF  NO  ARGUMENTS 

ADDRESS  OF  RETURNED  VALUE 

COPY  LENGTH 

IS  THIS  THE  NUMBER? 

IF  EQ  YES 

IF  MI  NUMBER  NOT  THERE 

DECREMENT  LOOP  COUNT 

IF  NE  NOT  AT  END  OF  LIST 


(continued  on  next  page) 
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Example    8-1    (Cont.)      Code    for    SUPER. MAC 


20$: 

MOV 

#-l,(R5) 

RETURN 

309: 

SUB 

R2,R3 

INC 

R3 

MOV 

R3,(R5) 

RETURN 

.END 

;    END    OF    LIST    PASS    BACK    ERROR 

;    NUMBER    FOUND    -    GET    INDEX    INTO    LIST 
;    RETURN    INDEX 


Example  8-2  Memory  Allocation  Map  for  SUPER 


SUPER. TSK;1   Memory   allociition  map     TKB  M40.10 
29-DEC-82         15:04 


Page  1. 


Partition  name  ;  GEN 

Identification  :  0203 

Task   UIC       :  (301,55) 

Task  atttibutes:  -HD.PI 

Total  address  windows:  1. 

Task   image   size   :  160.  words 

Task  address  limits:  000000  000473 

R-W  disk  blk  limits:  000002  000002  000001  00001. 

*••  Root  segment:  CMPAL 


R/W  m«?m   limits:  000000  000473  000474  00316. 
Disk  blk  limits:  000002  000002  000001  00001. 


Memory  allocation  synopsis: 
Section 


Title   Ident   File 


.  BLK.  :  (RW,I,[.CL,REL,CON) 


000000  000474  00316. 

000000  000136  00094.  CMPAL  0203    SYSLIB.0LB!6 

000136  000136  00094.  CMPAL  0203    SYSL.TB;OLB;  6 

000274  000136  00094.  SUPER     01    SUPER. 0BJ;3 

000432  000042  00034.  SAVAL  00      SYSLIB.0LB;6 


• 


Global  symbols: 

SEARCH  000352-R   SORT    000274-R   $CMPAL   000022-R   $CMPCS  000110-R   $SAVAL  000432-R 


***  Task  builder  statistics: 


Total  work  file  references:  320. 
Work   file   reads:  0. 
Work   file  writes:  0. 
Size  of  core  pool:  6988. 
Size  of  work  file:  1024. 


Elapsed  time:O0 :00 :04 


words  (27.  pag-is) 
words  (4.  pages) 
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Example  8-3   Completior-  Routine,  $CMPCS,  from  SYSLIB.OLD 


.TITLE   CMPAL 
.IDENT   /0204/ 


COPYRIGHT  (c)  1983  BY 

DIGITAL  EQUIPMENT  CORPORATION,  MA.NARO 

MASSACHUSETTS.   ALL  RIGHTS  RESERVED. 


THIS  SOFTWARE  IS  FURNISHED  UNDER  A  LICENSE  AND  HAY  BE  USED 
AND  COPIED  ONLY  IN  ACCORDANCE  WITH  THE  TERMS  OF  SUCH  LICENSE 
AND  WITH  THE  INCLUSION  OF  THE  ABOVE  COPYRIGHT  NOTICE.  THIS 
SOFTWARE  OR  ANY  OTHER  COPIES  THEREOF,  MAY  NOT  BE  PROVIDED  OR 
OTHERWISE  MADE  AVAILABLE  TO  ANY  OTHER  PERSON.  NO  TITLE  TO  AMD 
OWNERSHIP  OF  THE  SOFTWARE  IS  HEREBY  TRANSFERED. 

THE  INFORMATION  IN  THIS  DOCUMENT  IS  SUBJECT  TO  CHANGE  WITHOUT 
NOTICE  AND  SHOULD  NOT  BE  CONSTRUED  AS  A  COMMITMENT  BY  DIGITAL 
EQUIPMENT  CORPORATION. 

DIGITAL  ASSUMES  NO  RESPONSIBILITY  FOR  THE  USB  OR  RELIABILITY  OP 
ITS  SOFTWARE  ON  EQUIPMENT  THAT  IS  NOT  SUPPLIED  BY  DIGITAL. 


, ENABL   LC 


This  module  supports  the  "new"  transfer  vector  format  generate<*  by 
the  tt'Skbuilder  for  encering  super  mode  libraries.   This  format 
optimized  for  speed  and  size  and  supports  user  data  space  tasks. 

The  CSM  dispatcher  routine  and  the  stondard  completion  routines, 
$CMPAL  and  SCMfCS  are  included  in  this  module  due  to  the  close 
interaction  betw-ien  them. 


**-CSM  Dispatcher-Dispatch  CSM  entry 

This  module  must  be  linked  at  virtual  zero  in  the  supervisor  mode 
library.   It  is  entered  via  a  four  word  transfer  vector  of  the  form: 


MOV 

CSM 


t completion-routine,- (SP) 
•routine 


Note:  Immediate  mode  emulation  of  the  CSM  instruction  is  required 
in  the  executive. 

The  CSM  instruction  transfers  control  to  the  address  contained  in 
supervisor  mode  virtual  10.   At  this  point  the  stack  is  the  following: 

(SP)  routine  address 

2(SP)  PC  (past  end  of  transfer  vector) 

4(SP)  PS  with  condition  codes  cleared 

6(SP)  Completion-routine  address 

10 (SP)  Return  address 


(continued  on  next  page) 
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Example   8-3    (Cont.)      Completion    Routine,    $CMPCS,    from  SYSLIB.OLD 


A  routine   acldress   of    0    is    special    cased    to   support    return    to 
supervisor   mode    from  a    user   mode   debugging   aid    (GOT) .       In   this   case 
stack    is    the    foDowing: 

(SP)  zero 

2(SP)  PC    from  CEM   to  be   discarded 

4(SP)  PS    from  CSM    to   be   discarded 

6(SP)  Super   mode    PC   supplied   by  debugger 

10 (SP)  Super  mode    PS   supplied   by  debugger 

To  allow  positioning   at    virtual    zero,    this   code  must   be    in   the  blank 
PSECT  which    is    first    in    the   TKBs    PSECT  ordering. 

. PSECT 
.BNABL      LSB 

;    Debugger    return    to   super   mode   entry.    Must    start    at   virtual    zero 

CMP  (SP)+,(SP)+  ;    Clean   off    PS   and    PC   from  CSM 


**-9SRTI-SUPER  mode    RTI 

This  entry  point  performs  the  necessary  stack  management  to  allow 

an  RTI  from  super  mode  to  eitner  super  mode  or  user  mode. 

The  is  as  required  for  an  RTI; 


$SRTI I 


(SP) 
2(SP) 

TST 
BR 


Super  mode  PC 
Super  mode  PS 


2(SP) 
709 


;  Returning  to  usei  mode? 
;  Join  common  code 


;  CSM  transfer  address,  this  word  must  be  at  virtual  10  in  super  mode 


•WORD    CSMSVR 
;  Dispatch  CSM  entry 


CSMSVR:  MOV 
JMP 


6(SP)  ,2{SP) 
e(SP)  + 


;  CSM  dispatcher  entry 


;  Set  completion  routine  address  for  RETURN 
;  Transfer  to  super  mode  library  routine 


;  **-$CMPAL-Completion  routine  which  sets  up  NZVC  in  the  PS 

f 

;  Copy  all  condition  codes  to  stacked  PS,   Current  stack: 


(SP) 
2(SP) 
4(SP) 


PS  with  condtion  codes  cleared 

Completion  routine  address  (to  be  discarded) 

Return  address 


$CMPAL::BPL 
BNE 
BVC 
BIS 
BR 

10$:  BIS 
BR 


40$ 

20$ 

10$ 

#16,  (SP) 

$CMPCS 

♦  14, (SP) 

$CMPCS 


Set  NZV 
Set  NZ 


(continued  on  next  page) 
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Example   8-3    (Cont.)      Completion   Routine,    $CMPCS,    from   SYSLIB.OLD 


20$: 

BVC 

30$ 

BIS 

#12, (SP) 

Set  NV 

BR 

SCMPCS 

30$: 

BIS 

#10,  (SP) 

Set  N 

BR 

$CMPCS 

t 

40$: 

BNE 

60$ 

t 

BVC 

50$ 

BIS 

#6,  (SP) 

Set  ZV 

BR 

$CMPOS 

50$: 

BIS 

#4,(SP) 

Set  Z 

BR 

$CMPCS 

60$: 

BVC 

SCMPCS 

BIS 

12, (SP) 

•  Set  V 

;  **-$CMPCS-Completion    routine   which    sets    up   only  C    in    the    PS 

r 

;  Copy  only  carry  to  stacked  PS.   Current  stack: 

; 

}         (SP)    PS  with  condtion  codes  cleared 

t  2(SP)    Completion  routine  address  (to  be  discarded) 

J       4(SP)    Return  address 


$CMPCS: 

:ADC 

(SP) 

MOV 

4(SP)  ,2(SP) 

MOV 

(SP)+,2(SP) 

70$: 

BPL 

80$ 

MOV 

#6,-(SP) 

ADD 

SP,  (SP) 

MTPI 

SP 

80$: 

RTT 

Set  up  carry 

Setup  return  address  for  RTT 

And  PS.  Returning  to  super  mode? 

If  PL  yes 

Number  of  bytes  for  (SP) ,  PS,  and  PC 

Compute  clean  stack  value 

Set  up  previous  stack  pointer 

Return  to  previous  mode  and  caller 


.DSABL   LSB 


.END 


Example  8-4   Code  for  TSUP.MAC 


.TITLE   TSUP 
.IDENT   /Ol/ 


WRITE: 
READIN: 

lARRAY: 

LEN: 

lART: 

INDEX: 

GOT: 

ARGBLK: 

EDBUF: 


.MCALL   QI0W$,DIR$,QI0W$S 
QI0W$    I0.WVB,5,1, , , ,<O0T, ,40> 
QI0W$    I0.RVB,5,1, , , ,<0UT,5> 


.BLKW 
.BLKW 
•  BLKW 
.WORD 
.BLKW 

.BLKW 


12. 

1 

1 

0 

100. 

10. 


(continued  on  next  page) 
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Example  8-4  (Cont.)   Code  for  TSUP.MAC 


FHTl:  .ASCIZ  /%2SARRAY(%0)-/ 

PMT2:  .ASCIZ  /%N%2SNUHBER  TO  SEARCH  FOR?/ 

FMT3:  .ASCIZ  /%N%2S%0  WAS  POUND  IN  ARRAY(%D)/ 

PHT4:  .ASCIZ  /%N%2S%D  WAS  NOT  IN  ARRAY/ 

FMT5:  .ASCIZ  /t2SARRAY(%D)-«D/ 


START: 


55: 


10$: 


20$: 


.EVEN 

MOV 
MOV 

CLR 
DEC 
BNE 
MOV 
MOV 

MOV 

MOV 

INC 

CALL 

CALL 

MOV 

BEQ 

INC 

CMP 

BNE 

MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
CALL 


«IARRAy,RO 
«10,R1 

(R0)  + 

Rl 

5$ 

•lARRAY.RO 

•INDEX, R2 

#FMT1,R1 

(R2) ,EDBUF 

EDBUP 

PRINT 

READ 

lART,  (RO)-^ 

20$ 

(R2) 

(R2),*10. 

10$ 

(R2) ,LEN 

•ARGBLK,R5 

»2,(R5)+ 

tlARRAY, {^5)* 

#LEN, (R5) 

#ARGBLK,R5 

SORT 


GET  ADDRESS  OP  ARRAY 
SET  LENGTH  OF  ARRAY 

INITIALIZE  ARRAY 
LOOP 


FORMAT  SPECIFICATION  (ADDRESS 
OF  INPUT  STRING) 
GET  INDEX 

PRINT  MESSAGE 

READ  INPUT 

PUT  BINARY  KEYBOARD  INPUT  INTO  ARRAY 

ZERO  MARKS  END  OF  INPUT 


IF  NE  YES 

CALCULATE  LENGTH  OP  ARRAY 
GET  ADDRESS  OF  ARGUMENT  BLOCK 
NUMBER  OP  ARGUMENTS 
PUT  ADDRESS  OF  ARRAY 


SORT  ARRAY 


;+ 

;Task 
;cont 
;the 
;cont 

;- 


30$: 


Builder  replaced  call  to  SORT  subroutine  in  SUPLIB  with  4-word 
ext  switching  vector.  Flow  of  control  switches  to  SUPLIB  via 
vector  and  back  via  the  completion  routine  $CMPCS.  TSUP 
inues  excuting  at  the  next  instruction. 


CLR  R2 

NOV  «IARRAY,R0 

INC  R2 

NOV  R2, EDBUP 

MOV  (R0)+,EDBUF+2 

MOV  #FMT5,R1 

CALL  PRINT 

CMP  R2,LEN 

BLT  30$ 

MOV  »FMT2,R1 


GET  ARRAY  ADDRESS 

INCREMENT  INDEX 

GET  INDEX  FOR  PRINT 

GET  CONTENTS  OF  ARRAY 

GET  ADDRESS  OF  FORMAT  SPECIFICATION 

MORE  TO  PRINT? 

IP  LE  YES 

GET  ADDRESS  OF  FORMAT  SPECIFICATION 


(continued  on  next  page) 
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Example  8-4  (Cont.)   Code  for  TSUP.MAC 


CALL 

PRINT 

CALL 

KEAD 

MOV 

»ARGBLK,R5 

NOV 

#4,(R5)+ 

NOV 

#IART,(R5)+ 

NOV 

•lARRAY, (RS)+ 

NOV 

fLEN,(R5) * 

NOV 

♦INDEX, (R5) 

NOV 

*ARGBLK,RS 

CALL 

SEARCH 

OUTPUT  MESSAGE 
READ  RESPONSE 

SET  NUMBER  OF  ARGUMENTS 

SET  ADDRESS  OF  NUMBER  LOOKING  FOR 

SET  ADDRESS  OF  ARRAY 

SET  ADDRESS  OF  LEN  OF  ARRAY 

ADDRESS  OF  RESULT 

SEARCH  FOR  NUMBER  IN  lART 


;Call  to  SUPLIB  for  SEARCH  subroutine. 

; 


40$: 


1009! 


T»T 

INDEX 

•LT 

40$ 

NOV 

lART.EDBUF 

NOV 

INDEX,EDBUF4^2 

NOV 

#FMT3,R1 

CALI- 

PRINT 

BR 

IOCS 

NOV 

»FMT4,R1 

NOV 

IART,EDBUF 

CALL 

PRINT 

CALL 


$EXST 


WAS  NUMBER  FOUND? 

IF  LT  NO 

GET  NUMBER  LOOKING  FOR 

GET  ARRAY  NUMBER 

GET  FORMAT  ADDRESS 

DONE 

GET  FORMAT  ADDRESS 
GET  NUMBER 


;  EXIT  WITH  STATUS 


PRINT: 


CALL 

SSAVAL           ; 

NOV 

#OUT,R0          ; 

MOV 

»EDBUF,R2        ; 

CALL 

SEDMSG 

MOV 

Rl,WRITE+Q.I0PL+2 

OIR$ 

•WRITE           ; 

RETURN 

SAVE  ALL  REGISTERS 

ADDRESS  OF  OUTPUT  BLOCK 

START  ADDRESS  OF  ARGUMENT  BLOCK 

FORMAT  MESSAGE 

;  PUT  LENGTH  OF  OUTPUT 

LlLOCK  INTO  PARfMETER  BLOCK 

WRITE  OUTPUT  BuOCK 


READ: 


CALL 

$SAVAL 

DIR$ 

IREAOIN 

MOV 

♦OUT,R0 

CALL 

SCDTB 

MOV 

Rl,  lART 

RETURN 

;  SAVE  ALL  REGISTERS 
READ  REQUEST 
GET  KEYBOARD  INPUT 

;  CONVERT  KEYBOARD  INPUT  TO  BINARY 

;  PUT  INPUT  INTO  BUFFER 


.END 


START 
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Example    8-5      Memory    Allocation    Map    for    TSUP 


TSUP.T:iK;l   Memory   allocation   map      TKB   M40.10  Page    1 

29-DEC-82         15:01 


Partition  name  :  GEN 

Identification  :  01 

Task   UIC       :  (301,55] 

Stack     limits:  000274  001273  001000  00512. 

PRG  xfr  address:  002130 

Total  address  windows:  2. 

Task   image   size   :  1344.  words 

Task  address  limits:  000000  005133 

R-W  disk  blk  limits:  000002  000007  000006  00006. 

***  Root  segment:  TSUP 

R/W  mem   limits:  000000  005133  005134  02C52. 
Disk  blk  limits:  000002  000007  000006  00006. 

Memory  allocation  synopsis: 

Section  Title   Ident   File 


.  3LK.:(RW,I,LCL,RBL,C<'  5)  001274  002334  01244. 

001274  001234  00668.  TSOP    01      TSOP.OBJ;22 

CMPAL  : (RW, I,LCL,REL,CON)  000000  000474  00316. 

PURSD  : (RO, I,LCL,REL,CON)  003630  000076  00062. 

POR$I  : (RO,I,LCL,REL,CON)  003726  000752  00490. 

$$RESL: (RO, I ,LCL,REL,CON)  001700  000212  00138. 

SSSLVC: (RO, I,LCL,REL,CON)  005112  000020  00016. 

TSUP.TSK;1  Memory  allocatior.  map   TKB  M40.10       Page  2 
29-DEC-82    15:01 


***  Task  builder  statistics: 

Total  work  file  references:  2477. 

Work   file   reads:  0. 

Work   file  w..ites:  0. 

Size  of  core  pool:  6988.  words  (27.  pages) 

Size  of  work  file:  1024.  words  (4.  pages) 


Elapsed  t ime :00 :00 :05 


TSUP  prompts  von  to  enter  numbers  at  your  terminal.  It  calls  a 
subroutine  in  SUPER  to  sort  the  numbers.  Then  it  displays  the  numbers 
you  entered  as  array  entries  and  prompts  you  to  request  a  number  to 
search  for.  TSUP  calls  a  subroutine  in  SUPERLIB  to  search  for  the 
number.  Finally,  TSUP  indicates  at  your  terminal  either  that  the 
number  was  not  found  or  the  array  location  in  which  the  number  is 
stored . 
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8.7.3.1  Building  SDPER  -  To  build  SUPER  in  UFD  [301,55]  on  SY:,  use 
the  following  task-build  command  sequence: 

TKB>SUPER/-HD/L I /PI, SUPER/MA, SUPER= 

TKB>LB: ((l,2]]SYSLIB/LB:CMPAL,Sy: [ (301,55] ] SUPER 

TKB>/ 

Enter  Options: 

TKB>STACK=0 

TKB>PAR=GEN:0:2000 

TKB>CMPRT=$CMPCS 

TKB>GBLXCL-$SAVAL 

TKB>// 

SUPER  is  build  without  a  header  or  stack.  It  is  position  independent 
and  has  only  one  program  section,  named  .BLK.  The  /LI  switch 
accomplishes  this,  eliminating  progr^Ti  nection  name  conflicts  between 
the  library  and  the  referencing  task. 

The  completion  routine  module  of  SYSLIB,  CMPAL,  is  specified  first  in 
the  input  line.  The  library  will  run  In  partition  GEN  at  0  and  is  not 
more  than  IK. 

The  GBLXCL  option  excludes  $SAVAL  from  the  library's  .STB  file.  You 
exclude  $SAVAL  from  the  .STB  file  because  the  referencing  task,  TSUP, 
also  calls  $SAVAL.  If  TSUP  finds  $SAVAL  in  the  .STB  file  of  SUPER,  it 
will  not  link  a  separate  copy  of  $SAVAL  into  its  task  image  from 
SYSLIB.  If  TSUP  cannot  link  to  a  copy  of  $SAVAL  that  is  mag oed 
through  user  APRs,  the  TSUP  would  call  $SAVAL  as  a  subroutine  residing 
within  the  supervisor-mode  library,  but  without  the  necessary 
mode-switching  vector  and  completion  routine  support.  This  option 
forces  TKB  to  link  $SAVAL  from  SYSLIB  into  the  task  image  for  TSUP. 

The  memory  allocation  map  in  Example  8-2  shows  the  following: 

•  SUPER  begins  at  virtual  0. 

•  The  completion  routine,  $CMPAL,  is  linked  into  the  library 
from  SYSLIB  at  virtual  0. 

•  The  entry  point  $CKPAL  is  located  at  virtual  22,  SEARCH  is 
located  at  35,  and  sort  is  located  at  274.  All  of  these  entry 
points  are  relocatable. 


8.7.3.2  Building  TSUP  -  Use  the  following  task-build  command  sequence 
to  build  a  task,  TSUP,  that  links  to  SUPER: 

TKB>TSUP,TSUP=TSUP 

TKB>/ 

Enter  Options: 

TKB>RESSUP=SUPER/SV: 0 

TKB>// 

This  command  sequence  tells  TKB  to   include   in   the   logical   address 

space   of  TSUP  a  user-owned,  supervisor-mode  library  named  SUPER.   TKB 

includes  a  4-word,  mode-swi,tching  vector  within   the   task  image   for 

each  call  to  a  subroutine  within  the  library.   The  library  is  position 

independent  and  is  mapped  with  supervisor  1-space   APRO.  This   is   a 

requirement   for   CSM   libraries   because   the  CSM  expects  to  find  the 
entry  point  of  the  completion  routine  at  location  10, 
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The  memory  allocation  map  for  TSUP  (Example  8-5)  shows: 

•  $CMPAL  is  linked  from  the  .STB  file  of  the  library  and  begins 
at  location  0. 

•  The  mode-switching  vectors  begin  at  005136  and  are  16.  bytes. 
That  means  that  TSUP  calls  subroutines  within  the  library  2 
times  (4  words  per  vector). 

•  The  initiation  routine  $SUPr.  is  located  at  4700. 

•  The  SEARCH  and  SORT  subroutines  that  were  located  at  virtual 
112  and  32,  respectively,  in  the  virtual  address  space  of 
SUPER  have  been  relocated  to  the  mode-switching  vectors 
residing  at  5136  and  5146  respectively,  in  TSUP. 

•  The  SAVAL  module  from  SYSLIB  containing  $SAVAL  has  been  linked 
into  the  ta<«k  image  instead  of  including  $SAVAL  from  the 
library's  .STB  file. 


8.7.3.3  Running  TSOP  •  After  building  SUPER  and  TSUP  as  indicated  in 
the  task-build  command  sequence  discussed  prc\ lously,  you  install 
SUPER  and  run  TSUP.   TSUP  prompts  you  for  a  numbe. : 

ARRAY  (X) 


The  position  in  which  to  store  the  number  in  the  array.  You 
enter  a  number.  TSUP  stores  the  number  in  the  array  and 
prompts  you  again  for  a  number.  This  continues  until  you 
either  have  entered  a  0,  an  illegal  number,  or  10  numbers. 
Then  TSUP  calls  the  SORT  routine  in  SUPER. 

You  enter  a  number.   TSUP  calls  the  SEARCH   routine   in  SUPER.    Then 
TSUP  outputs  a  message  indicating  whether  the  number  was  in  the  array. 


8.7.4  The  CSM  Library  Dispatching  Process 

When  you  build  the  referencing  task,  if  you  specify  the  SV  argument  to 

the    RESSUP   or    SUPLIB   option,    then  TKB   includes   a   4-word 

context-switching  vector  for  each  call  to  a  subroutine  in  the  library. 

This  has  been  very  generally  discussed  in  Section  8.2.   This  section 
discusses  the  CSM  library  vector  in  detail. 

CSM  mode  switching  occurs  as  follows: 

1.  The  vector  is  entered  with  the  return  address  on  top  of  the 
stack  (TOS) . 

2.  The  vector  pushes  the  completion  routine  address  on  the 
stack. 

3.  A  CSM  instruction  is  executed  with  the  supervisor-mode  entry 
point  as  thf  immediate  addressing  mode  parameter.  The  CSM 
instruction : 

a.   Evaluates  the  source  parameter  and  stores  the  entry  point 
address  in  a  temporary  register  
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b.  Copies  the  usee  stack  pointer   to   the  supervisor   stack 
pointer 

c.  Places  the  current  PS  and   PC  on   the   supervisor   stack 
clearing  the  condition  codes  in  the  PS 

d.  Pushes  the  entry  point  address  on  the  supervisor  stack 

e.  Places  the  contents  of  location  10  in  supervisor   I-space 
into  the  PC 

The  stack  looks  like  this  when  the  processor  begins  to  execute  at   the 
contents  of  virtual  10  in  supervisor  mode: 


e 


user  sp > 


K 


return  address 

completion  routine  address 

PS 

PC 


super  sp  >   entry  point  address 

The  most  important  aspect  of  how  the  CSM  library  mode-switching  vector 

works   in   that   the  processor   begins  executing   at  the  contents  of 

virtual  10  in  supervisor  mode.   This  is  why   the   completion   routine 

must   be   located   at  virtual  0,  so  that  virtual  location  10  is  within 
the  completion  routine. 


8.8   CONVERTING  SCAL  LIBRARIES  TO  CSM  LIBRARIES 

You  can  easily  convert  your  SCAL  libraries  to  CSM  libraries. 
Rebuilding  a  task  on  an  RSX-llM-PLUS  V2.0  system  or  later  that  linked 
to  a  library  on  a  VI. 0  system  requires  that  you  rebuild  tlie  library 
also.  Rebuild  the  library  specifying  the  completion  routine  as  the 
first  input  module.  If  the  library  was  not  built  to  run  at  a  starting 
address  of  0  in  its  partition,  rebuild  it  so  that  it  does  begin  at  0 
to  enable  TKB  to  find  the  completion  routine. 


8.9   OSING  SOPBRVISOR-MODE  LIBRARIES  AS  RESIDENT  LIBRARIES 

Supervisor-mode  libraries  can  double  as  conventional  resident 
libraries.  For  position-independent,  supervisor-mode  libraries,  you 
rebuild  the  referencing  task  using  the  RESLIB  option  instead  of  the 
RESSUP  option.  Indicate  the  first  available  user-mode  APR  that  you 
want  to  map  the  library.  For  CSM  libraries  this  will  always  change, 
because  you  cannot  map  a  shared  region  with  APR  0.  You  do  not  have  to 
rebuild  the  library. 

For  absolute  supervisor-mode  libraries,  rebuild  the  referencing  task 
using  the  RESLIB  option  instead  of  the  RESSUP  option.  Rebuild  the 
library  only  if  the  beginning  partition  address  in  the  PAR  option  is 
incompatible  with  the  address  limits  of  your  referencing  task. 


8.10   MULTIPLE  SOPBRVISOR-MODE  LIBRARIES 

A  user  task  can  reference  multiple  supervisor-mode  CSM  libraries. 
However,  all  the  CSM  libraries  must  use  the  completion  routine  that 
begins  at  virtual  zero  in  supervisor-mode  instruction  space. 
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8.11   LINKING  A  RESIDENT  LIBRARY  TO  A  SUPERVISOR-NODE  LIBRARY 

You  can  link  a  conventional   resident   library   to  a   supervlsor-mocle 
library  using  the  following  command  sequence: 

TKB>F4PRES/-HD,F4PRES,F4PRES,LB: [ [ 1 , I] ] F4PRES- 

TKB>F4PRES/LB 

TKB>/ 

Enter  Options: 

TKB>STACK=0 

TKB>SUPLIB=FCSFSL:SV 

TKB>PAR=F4PRES: 14000 0:20000 

TKB>// 

This  command  sequence  shows  you  how  to  link  F4PRES  to  FCSFSL. 


8.12   LINKING  SUPERVISOR-MODE  LIBRARIES 

You  cannot  link  supervisor-mode  libraries  together,  and  you  cannot 
link  a  supervisor-mode  library  to  a  resident  user-mode  library. 
Calling  a  user-mode  library  is  not  possible  because  its  code  is  not 
mapped  through  the  I-space  APRs  while  in  the  supervisor-mode  library. 
However,  you  can  link  user-mode  libraries  to  a  supervisor-mode 
library. 


8.13   WRITING  YOUR  OWN  VECTORS  AND  COMPLETION  ROUTINES 

You  can  write  your  own  mode-switching  vectors  and  completion  routines. 
This  may  be  necessary  for  threaded  code.  If  you  use  your  own  vectors, 
build  them  into  the  task  and  use  the  -SV  switch  on  the  RBSSUP  or 
RESLIB  option  when  you  build  the  referencing  task.  If  you  create  your 
own  completion  routines,  write  your  completion  routine  to  resemble  the 
system-supplied  completion  routines  (see  Example  8-3)  as  much  as 
possible.  If  you  do  not  retain  the  last  three  lines  of  code  as 
indicated  in  Example  8-3,  then  if  the  Executive  processes  an  interrupt 
before  the  mode  switch  back  to  user  mode  has  completed,  your  task  may 
crash. 


8.14   OVERLAID  SUPERVISOR-MODE  LIBRARIES 

It  is  possible   to   use  overlaid   supervisor-mode  libraries.    Three 
restrictions  must  be  noted  when  building  these  libraries: 

•  The  completion  routine  for  the  library  must  be  in  the  root. 

•  Only  one  level  of  overlay  is  allowed.  This  is  illustrated  in 
Figure  8-4. 

•  Although  the  Fast  Task  Builder  (FTB)  can  link  to 
supervisor-mode  libraries,  it  cannot  link  to  overlaid 
supervisor-mode  libraries. 
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B 


ROOT 
ALLOWED 


LJ  U  U 


ROOT 

ALLOWED 


ROOT 

NOT  ALLOWED 


Figure  8-4   Overlay  Configuration  Allowed  for 
Supervisor-Mode  Libraries 
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CHAPTER  9 
MULTIUSER  TASKS 


9.1   INTRODUCTION 

A  multiuser  task  is  a  task  that  shares  the  pure  (read-only)  portion  of 
its  code  with  two  or  more  copies  of  the  impure  (read/write)  portion  of 
its  code.  When  the  system  receives  an  initial  run  request  for  a 
multiuser  task,  a  copy  of  both  the  read-only  and  read/write  portions 
of  the  task  are  read  into  physical  memory.  As  long  as  the  task  is 
running,  all  subsequent  run  requests  for  it  result  in  the  system 
duplicating  only  the  read/write  portion  of  the  task  in  physical 
memory.   Thus,  multiuser  tasks  are  memory  efficient. 

When  you  build  a  task,  you  designate  it  as  multiuser  by  applying  the 
/MU  switch  to  the  task  image  file.  This  switch  directs  the  Task 
Builder  to  create  two  regions  for  the  cask.  One  region  (region  0) 
contains  the  read-write  portion  of  the  task;  the  other  r<sg'on  (region 
1)  contains  the  read-only  portion  of  the  task. 


As  with  all  ct 
determine   its 
address  space 
single   user 
hardware   prot 
portions  of 
them  in  separa 
It   allocates 
includes  the  t 
APRS    to    th 
allocation. 


her  tasks,  TKB  uses  a  program  section's  access  code  to 
placement  within  a  multiuser  task's  image.  It  divides 
into  read/write  and  read-only  sections.  Unlike  in  a 
task,  however,  the  read-only  portion  of  the  task  is 
ected.  In  addition,  TKB  separates  the  read/write 
a  multiuser  task  from  the  read-only  portions  and  places 
te  regions  at  opposite  ends  of  the  task's  address  space, 
the  low-address  APRs  to  the  read/write  portion  (which 
ask's  header  and  stack  area)  and  the  highest  available 
e    read-only   portion.    Figure   9-1   illustrates   this 


For  I-  and  D-space  multiuser  tasks,  in  addition  to  having  the 
multiuser  task  divided  into  regions  of  read-only  PSECTs  and  read/write 
PSECTs,  these  regions  themselves  are  divided  into  I-space  areas  and 
D-space  areas.  All  of  the  following  combinations  must  be  present  in 
an  I-  and  D-space  multiuser  task: 

•  .PSECT  psectnamew,  RO,  I,  ... 

•  .PSECT  psectnamex,  RW,  I,  ... 

•  .PSECT  psectnamey,  RO,  D,  ... 

•  . PSRCT  psectnamez,  RW,  D,  ... 

If  neither  the  read-only  nor  the  read/write  portion  of  the  task 
contains  memory-resident  overlays,  TKB  allocates  two  window  blocks  in 
the  header  of  the  task.  When  the  task  is  installed,  the  INSTALL 
processor  will  initialize  these  window  blocks  as  follows: 

•  Window  block  0  describes  the  range  of  virtual  addresses  (the 
window)  for  the  read/write  portion  of  the  task.  This  region 
always  contains  the  task's  header. 
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•   Window  block  1  (iescribes  the  range  of   virtual   addresses   for 
the  read-only  portion. 

Figure   9-2   below   shows   the   window-to-region   relationship   of    a 
multiuser  task. 


APR  7  — 
APR6  — 
APR  5  — 
APR  4  — 
APR3  — 

APR  2  — 
APR  1  — 

APR  0  — 


UNUStU 


READONLY 
PROGRAM 
SECTIONS 


UNUSED 


READ'WRITE 
PROGRAM 
SECTIONS 


I  HEADER  &  STACK 


Figure  9-1   Allocation  of  Program  Sections  in  a  Multiuser  Task 


9.1.1   Overlaid  Multiuser  Task 

If  a  multiuser  task  is  an  overlaid  task  (described  in  Chapter  3),   the 
read-only  portion  of  the  task  can  be  made  up  of  the  following: 

•  The  read-only  program  sections  of  the  root  segment 

•  Branches  of  an  overlay  structure  it   the   complete   branch   is 
memory  resident  and  read-only 

•  A  co-tree  structure  if  the  entire  co-tree  is   memory   resident 
and  read-only. 


9.1.2   Disk  Image  of  a  Multiuser  Task 

The  disk  image  of  a  a;  Itiuser  task  is  som3what  different  from  that  of 
a  single-user  task.  The  read-only  portion  of  the  task  is  placed  at 
the  end  ot  the  disk  image.  The  relative  block  number  of  the  read-only 
portion  and  the  number  of  blocks  it  occupies  appearj  in  the  label 
block.  The  read-only  portion  of  the  image  is  described  in  the  <^irst 
library  descriptor  of  the  LIBRARY  REQUEST  section  of  the  label  block. 


(Refer  to  Appendix  B  for  more 
structures . ) 


information   on   the   task   image   data 
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HIGHEST  VIRTUAL 
ADDRESS 


WINDOW  BLOCK 
1 


WINDOW  BLOCK 
0 


LOWEST  VIRTUA 
ADDRESS 


UNUSED 


READONLY 


^^iWf^TW'* 


UNUSED 


READ/WRITE 


REGION  1 


REGION  0 


Figure   9-2     Windows    for   a   Multiuser   Task 


9.1.3      I-   and    D-Space   Multiuser    Tasks 

The   APR   and   window  block   assignment    in   an      I-      and      D-space 
task   differs    from   that    in   a   conventional   multiuser    task. 


multiuser 


D-space  APRs  map  the  read-write  and  read-only  PSECTs  that  have  the 
data  attribute.  Similarly,  I-space  APRs  map  the  read-write  and 
read-only  PSECTs  that  have  the  instruction  attribute.  Figure  9-3 
shows  the  APR  mapping  for  both  kinds  of  PSECTs  in  an  I-  and  D-space 
multiuser  task. 


TKB  needs  four  window  blocks  to  map  an  I-  and  D-space  multiuser  task. 
Window  blocks  0  and  1  map  region  0.  which  contains  the  read-write 
instruction  and  data  PSECTs.  Window  blocks  2  and  3  map  region  1, 
which  contains  the  read-only  instruction  and  data  PSECTs.  Figure  9-4 
illustrates  the  mapping  and  assignment  of  these  window  blocks  for  an 
I-  and  D-space  multiuser  task. 
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DATA  APRS 


DAPR7 


DAPR6 


DAPR5   — 


DAPR4 


DAPR3 


UNUSED 


READ-ONLY  DATA 
PROGRAM  SECTIONS 


UNUSED 


DAPR2  — 


DAPR1   — 


DAPRO 


READ-WRITE  DATA 
PROGRAM  SECTIONS 


HEADER  .  STACK 


INSTRUCTION  APRS 

UNUSED 

IAPR7   — 

READ-ONLY 

INSTRUCTION 

PROGRAM  SECTIONS 

IAPR6   — 

IAPR5  — 

IAPR4    — 

UNUSED 

IAPR3  — 


IAPR2 


IAPR1 


READ-WRITE 

INSTRUCTION 

PROGRAM  SECTIONS 


lAPRO  — !■ 


UNUSED  HEADER 


?K  noi-a? 


Figure  9-3   Example  Allocation  of  Program  Sections  in  an  I-  and 

and  D-Space  Multiuser  Task 


# 
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PHYSICAL 
MEMORY 


TASK 
WINDOW  BLOCKS 


WINDOW  BLOCK  3 


WINDOW  BLOCK  2 


WINDOW  BLOCK  1 


WINDOW  BLOCK  0 


READ-ONLY  D 


READ-ONLY  I 


READ-WRITE  D 
READ-WRITE  I 


>v 


)  REGION  1 


"N 


)  REGION  0 


m 


Figure  9-4   Windows  for  an  I-  and  D-Space  Multiuser  Task 


9.2   EXAMPLE  9-1:   BUILDING  A  MULTIUSER  TASK 

The  text  in  this  section  and  the  figures  associated  with  it  illustrate 
the  development  of  a  multiuser  task.  This  example  was  created  by 
concatenating  into  a  single  file  the  resident  library  file  (LIB. MAC) 
and  the  task  that  links  to  it  (MAIN. MAC)  from  Example  5-3.  It  is  not 
intended  to  represent  a  typical  multiuser  task  application.  However, 
it  does  illustrate  the  Task  Builder's  allocation  of  program  sections 
in  a  multiuser  task  and  that  is  its  primary  value.  The  concatenated 
source  file,  named  ROTASK.MAC,  for  this  example  is  shown  in  Example 
9-1. 
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Example   9-1,    Part    1      Source   Listing    for    ROTASK.MAC 


•TITLE 

ROTASK 

.IDENT 

/Ol/ 

.MCALL 

QIOW$S,EXIT$S 

OPl: 

.WORD 

1 

0P2: 

.WORD 

1 

ANS: 

.BLKW 

1 

OUT: 

.BLKW 

100. 

FORMAT: 

.ASCIZ 
.EVEN 

/THE  ANSWER  « 

START: 

NOV 

#ANS,-(SP) 

MOV 

#0P2,-(SP) 

MOV 

#0P1,-(SP) 

MOV 

#3   ,-(SP) 

MOV 

SP,R5 

CALL 

AADD 

CALL 

PRINT 

MOV 

SP,R5 

CALL 

SUBB 

CALL 

PRINT 

MOV 

SP,R5 

CALL 

MULL 

CALL 

PRINT 

MOV 

SP,R5 

CALL 

DIVV 

CALL 

PRINT 

EX1T$S 

%D,/ 


OPERAND  1 
OPERAND  2 
RESULT 

FORMAT  MESSAGE 


TO  CONTAIN  RESULT 

OPERAND  2 

OPERAND  1 

PASSING  3  ARGUMENTS 

ADDRESS  OF  ARGUMENT  BLOCK 

ADD  TWO  OPERANDS 

PRINT  RESULTS 

ADDRESS  OF  ARGUMENT  BLOCK 

SUBTRACT  SUBROUTINE 

PRINT  RESULTS 

ADDRESS  OF  ARGUMENT  BLOCK 

MULTIPLY  SUBROUTINE 

PRINT  RESULTS 

ADDRESS  OF  ARGUMENT  BLOCK 

DIVIDE  SUBROUTINE 

PRINT  RESULTS 


;**  PRINT  -  PRINT  RESULT  OF  OPERATION. 


PRINT:   MOV  #OUT,R0  ;  ADDRESS  OF  SCRATCH  AREA 

MOV  #F0RMAT,R1  ;  FORMAT  SPECIFICATION 

MOV  #ANS,R2  ;  ARGUMENT  TO  CONVERT 

CALL  $EDMSG  ;  FORMAT  MESSAGE 

QIOW$S  #I0.WVB,#5,#1,,, .<#OUT,R1,#40> 
RETURN  ;  RETURN  FROM  SUBROUTINE 

;**  FORTRAN  CALLABLE  SUBROUTINE  TO  ADD  TWO  INTEGERS 

.PSECT  AADD,RO,I,GBL,REL,CON 


AADD: : 

CALL 

$SAVAL 

•  SAVE  R0-R5 

MOV 

§2{R5) ,R0 

FIRST  OPERAND 

MOV 

§4(R5) ,R1 

•  SECOND  OPERAND 

ADD 

R0,R1 

SUM  THEM 

MOV 

Rl,e6(R5) 

STORE  RESULT 

RETURN 

RESTORE  REGISTERS  AND  RETURN 

(continued  on  next  page) 
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Example  9-1,  Part  1   Source  Listing  for  ROTASK.MAC 


FORTRAN  CALLABLE  SUBROUTINE  TO  SUBTRACT  TWO  INTEGERS 

.PSECT  subb,ro,i,gbl,ri::l,con 

SUBB::   CALL     $SAVAL  ;  SAVE  R0-R5 

FIRST  OPERAND 
SECOND  OPERAND 
SUBTRACT  SECOND  FROM  FIRST 
STORE  RESULT 
;  RESTORE  REGISTERS  AND  RETURN 


CALL 

$SAVAL 

MOV 

§2(R5),R0 

MOV 

§4(R5),R1 

SUB 

R1,R0 

MOV 

R0,§6(R5) 

RETURN 

;**  FORTRAN  CALLABLE  SUBROUTINE  TO  DIVIDE  TWO  INTEGERS 


DIVV: 


PSECT   DIVV,RO,I,GBL,REL,CON 


CALL 

$SAVAL 

'  SAVE  REGS  R0-R5 

MOV 

?2(R5) ,R3 

FIRST  OPERAND 

MOV 

e4(R5) ,R1 

•  SECOND  OPERAND 

CLR 

R2 

LOW  ORDER  16  BITS 

DIV 

R1,R2 

;  DIVIDE 

MOV 

R2,§6(R5) 

>  STORE  RESULT 

RETURN 

;  RESTORE  REGISTERS  AND  RETURN 

;**  FORTRAN  CALLABLE  SUBROUTINE  TO  MULTIPLY  TWO  INTEGERS 
.PSECT   MULL,RO,I,GBL,REL,CON 


MULL: 


CALL 

$SAVAL           , 

SAVE  R0-R5 

MOV 

92(R5) ,R0 

FIRST  OPERAND 

MOV 

94(R5) ,R1 

SECOND  OPERAND 

MUL 

R0,R1 

•  MULTIPLY 

MOV 

Rl,e6(R5) 

STORE  RESULT 

RETURN 

1  RESTORE  REGISTERS  AND  RETURN 

.END 

START 

Once  you  have  assembled  ROTASK,  you  can  build  it   with   the   following 
command  sequence: 

TKB>ROTASK/MU,ROTASK/-WI/-SP=ROTASK 

TKB>/ 

Enter    Options: 

TKB>ROPAR=RDONLY 

TKB>// 


This  command  sequence  directs  TKB  to   build   a   multiuser   (/MU)  task 

image   named   ROTASK. TSK   and   to   create  an  80-column  (/-WI)  map  file 

named  ROTASK. MAP.  Because  /-SP  is  attached  to  the  map  file,  TKB  does 
not  output  a  map  to  the  line  printer. 

The  ROPAR  option  specifier  that  the  system  is  to  load  the  read-only 
portion  of  the  task  into  a  partition  named  RDONLY.  Specifying  a 
separate  partition  for  the  task's  read-only  region  is  not  a  system 
requirement.  The  system  will  load  the  read/write  portion  into 
partition  GEN.  The  system  will  not  load  either  region  until  it 
receives  a  run  request  for  the  task. 

The  map  thiat  results  from  this  command  sequence  is  shown  in  Example 
9-1,  Part  2.  Note  that  TKB  has  added  one  field  to  the  task  attributes 
section  of  this  map  describing  the  disk  block  limits  of  the  read-only 
portion  of  the  task.  It  has  also  added  a  field  to  the  toot  segment 
portion  of  the  map  that  describes  the  memory  limits  of  the  read-only 
portion  of  the  task. 


Finally,  note  that 
sections   with   the 


TKB   has   allocated   space   for   all   the   program 
iread-only   attribute,   beginning  with  the  highest 
available  APR  (in  this  case,  APR  7). 
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Exaropla   9-1,    Part    2      Task   Builder    Map    for    ROTASK.TSK 


R0TASK.TSK;1 


Memory   allocation  map      TKB  M40.10 
lO-DBC-82         14:42 


PAGE  1 


Partition  name  :  GEN 

Identification  :  01 

Task   UIC       I  [7,62] 

Stack    Limits:  000274  001273  001000  00512. 

PRG  xfr  address:  001634 

Task  attributes:  MU 

Total  address  windows:  2. 

Task   image   size   :  1088.  words 

Task  address  limits:  000000  0041S7 

R-W  disk  blk  limits:  000002  000006  000005  0000 >. 

R-0  disk  blk  limits:  000007  000007  000001  00001. 

••*  Root  segment:  ROTAS K 


R/W  mem  limits:  000000  004157  004160  02160. 
R-0  mem  limits:  160000  160377  000400  00256. 
Disk  blk  limits:  000002  000006  000005  00005. 


Memory  allocation  synopsis: 

Section 

.  BLK. 

AADO 


Title   Ident   File 
ROTAS K  01 


(RW,I,LCL,REL,CON)  001274  002662  01458. 

001274  000530  00344.  ROTASK  01      ROTASK.OBJ;! 

(RO,I,LCL,REL,CON)  160000  000024  00020. 

160000  000024  00020.  ROTASK  01      SOTASK.OBJ; 1 

DDIV   : (RO,I,LCL,REL,CON)  160024  000026  00022. 

160024  000026  00022.  ROTASK  01      ROTASK.OBJ; 1 

MNUL   : (RO,I,LCL,REL,CON)  160052  000024  00020. 

160052  000024  00020.  ROTASK  01      ROTASK.OBJ;! 

SSUB   : (RO,I,LCL,REL,CON)  160076  000024  00020. 

160076  000024  00020.  ROTASK  01      ROTASK.OBJ; 1 

$$KESL:(RO,I,LCL,REL,CON)  160122  000212  00138. 


Global  symbols: 

AAOD    160000-R   DIW    160024-R   MULL    160052-R   SUES 


160076-R 


***  Task  builder  statistics: 


Total  work  file  references:  2145. 


Work   file   reads:  0. 

Work   file  writes:  0. 

Size  of  core  pool:  7086, 
Size  of  work  file 


words  (27.  PAGES) 


1024.  words  (4.  PAGES) 
Elapsed  time:00:00:07 
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CHAPTER  10 
SWITCHES 


You  use  switches  and  options  to  control  the  construction  of  your  task 
image.  This  chapter  provides  detailed  reference  information  on  all 
the  TKB  switches.   Chapter  11  describes  the  TKB  options. 


10.1   SWITCHES 

The  syntax  for  a  file  specification,  as  given  in  Chapter  1,  is: 

dev: ( group, member ] f i lename. type ; vers ion/swl/sw2 . . ./swn 

Optionally,  you  can  conclude  a  file  specification  with  one  or  more 
switches  (swl  ,sw2 ,  .  .  .swn)  .  When  you  do  not  specify  a  switch,  the  Task 
Builder  establishes  a   default  setting  for  it. 

You  designate  a  switch  by  a  2-  to  4-character  code  preceded  by  a 
slash  (/) .  If  you  precede  the  2-  to  4-character  code  with  a  minus 
sign  (-)  or  the  letters  NO,  TKB  negates  the  function  of  the  two 
characters.  For  example,  TKB  recognizes  the  following  settings  for 
the  switch  CP  (checkpointable): 

/CP        The  task  is  checkpointable. 
/-CP      The  task  is  not  checkpointable. 
/NOCP     The  task  is  not  checkpointable. 

In  some  cases,  two  particular  switches  cannot  both  be  used  in  a  file 
specification.  When  such  a  conflict  occurs,  TKB  selects  the 
overriding  switch  according  to  the  following  table: 


Switch 

/AC  (Ancillary 
Control  Processor) 

/EA  (Extended 
Arithmetic  Element) 

/CC  (Concatenated 
object  file) 


Switch 

/PR  (Privileged; 


/FP  (Floating 
Point  Processor) 

/LB  (Library  file) 


Overriding  Switch 
/AC 

/FP 

/LB 


For  example: 

MCR>TKB  IMG5=IN6, IN5/LB/CC 

TKB  3ssumes  that  the  input  file  IN5  is  a  library  file.  It  searches 
the  file  for  undefined  global  references.  It  does  not  include  in  the 
task  image  alx  of  the  modules  in  INS. 
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SWITCHES 

The  switches  that  TKB  recognizes  are  given  in  alphabetical  order  in 
Table  10-1.  Sections  10.1.1  through  10.1.30  give  detailed 
descriptions  of  each  switch,  in  alphabetical  order,  including: 

•  The  switch  format 

•  The  file(s)  to  which  the  switch  can  be  applied 

•  A  description  of  the  effect  of  the  switch  on  the  Task  Builder 

•  The  default  assumption  made  if  the  switch  is  not  present 

Table  10-1 
Task  Builder  Switches 

Appl ies 
Format  Meaning  to  File        Default 

/AC(:n]   Task  is  an  ancillary  control  pro- 
cessor . 

/AL      Task  can  be  checkpointed  to  space 
allocated  in  the  task  image  file. 

/CC       Input  file  consists  of  concatenated 
object  modules. 

/CM      Memory-resident  overlays  are  aligned 
on  256-word  physical  boundaries. 

/CO      Causes  TKB  to  build  a 
shared  common. 

/CP      Task  is  checkpointable. 

/CR      A  global  cross-reference  listing 

is  appended  to  the  memory  allocation 
file. 

/DA      Task  contains  a  debugging  aid.  .TSK,         /-DA     ' 

.OBJ 

/DL      Specified  library  file  is  a  re-         .OLB  /-DL 

placement  for  the  system  object 
module  library. 

/EA      Task  uses  extended  arithmetic  .TSK  /-EA 

element. 

/EL      Specifies  library  size  according        ,TSK  /-EL 

to  partition  size. 

/FP      Task  uses  the  Floating  Point  .TSK   /-FP  on  RSX-llM 

Processor.  /FP  on  RSX-llM-PLUS 


.TSK 

/-AC 

.TSK 

/-AL 

.OBJ 

/CC 

.TSK 

/-CM 

.TSK 
.STB 

/CO 

.TSK 

/-CP 

.MAP 

/-CR 

(continued  on  next  page) 
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Table  10-1  (Cont.) 
Task  BuilJer  Switches 


.TSK, 

/HD 

.STB 

.TSK 

/-ID 

.TSK 

/-IP 

Appl ies 
Format  Meaning  to  File        Default 

/FU       All  co-tree  overlay  segments  are         .TSK  /-FU 

searched  for  matching  definition  or 
reference  when  modules  from  the  de- 
fault object  module  library  are 
being  processed. 

/HD      Task  image  includes  a  header. 

/ID      Task  will  use  I-  and  D-space. 

/It'      Allows  TKB  to  inform  INS  that  the 
task  purposely  overmaps  the 
I/O  page. 

/CB      Input  file  is  a  library  file. 

/LI       Informs  TKB  to  build  a 
shared  library. 

/MA      Map  file  includes  information 
from  the  file. 

/MM      System  on  which  the  task  is  to 
run  has  memory  management. 

/MP      Input  file  contains  an  overlay 
description . 

/MU      Task  is  a  multiuser  task. 

/NM       Tells  TKB  to  inhibit  two 
diagnostic  messages. 

/PI      Task  is  position  independent. 

/PM      Postmortem  Dump  is  requested. 

/PR[:n]   Task  has  privileged  access  rights. 

/RO      Memory-resident  overlay  operator 
(!)  is  enabled . 

/SE       Messages  can  be  directed  to  the  .TSK  /SE 

task  by  means  of  the  Executive 
SEND  directive. 

1.  The  default  is  /MA  for  an  input  file,  and  /-MA  for  system  library 
and  resident  library  .STB  files. 

2.  The  default  for  the  memory  management  switch  is  /MM  if  the  host 
system  has  memory  managment  hardware,  and  /-MM  if  the  host  system  does 
not  have  memory  management  hardware. 

(continued  on  next  page) 


.OLB 

/-LB 

.TSK 

/-LI 

.STB 

.MAP, 

/MA 

OT 

/-maI 

.OBJ 

.TSK 

/MM 

or 

/-MM  2 

.DDL 

/-MP 

.TSK 

/-MU 

.TSK 

/-NM 

.TSK, 

/-PI 

.STB 

.TSK 

/-PM 

•  TSK 

/-PR 

.TSK 

/RO 
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Table  10-1  (Cont.) 
Task  Builder  Switches 


Appl ies 
Format  Meaning  to  File         Default 

/SG      Allocates  task  program  sections         .TSK  /-SG 

alphabetically  by  access  code  ( RW 
fol lowed  by  RO)  . 

/SH      Short  memory  allocation  file  is         .MAP  /SH 

requested . 

/SL      Task  is  slaved  to  an  initiating         .TSK  /-SL 

task . 

/SP       Spool  map  output.  .MAP  /SP 

/SQ       Allocates  task  program  sections  .TSK  /-SQ 

in  input  order  by  access  code. 

/SS      Selective  search  for  global  .OBJ  /-SS 

symbols . 

/TR      Task  is  to  be  traced.  .TSK  /-TR 

/WI      Memory  allocation  file  is  printed        .MAP  /WI 

at  a  width  of  132  characters. 

/XH       RSX-llM-PLUS  only  switch.   Task  is       .TSK  ^ 

to  have  an  external  header. 


/XT[:n]   TKB  exits  after  n  diagnostic.  .TSK  /-XT 

3.  The  default  is  ultimately  determined  by   the  /XHR  switch   in   the 
INSTALL .command ,  which  overrides  the  TKB  setting  except  for  /-XH. 
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AC 


10.1.1  /AC(:n)  --  Ancillary  Control  Processor 
File 

Task  image 
Syntax 

file. TSK/AC : 0=  f  i le , OBJ 

or 
file. TSK/AC: 4=f ile.OBJ 

or 


f i le. TSK/AC: 5= f ile.OBJ 


Pascr iption 


The  /AC  switch  informs  TKB  that  your  task  is  an  ancillary  control 
processor;  that  is,  it  is  a  privileged  task  that  extends  certain 
Executive  functions.  For  example,  the  system  task  FllACP  is  an 
ancillary  control  processor  that  receives  and  processes  FILES-11 
related  input  and  output  requests  on  behalf  of  the  Executive. 


Effect 


This  switch  also  informs  TKB  that  your  task  is  privileged.  TKB 
sets  the  AC  attribute  flag  and  the  privileged  attribute  flag  in 
your  task's  label  block  flag  word. 

The  value  of  n  is  an  octal  number  that  specifies  the  first  KT-11 
Active  Page  Register  (APR)  that  you  want  the  Executive  to  use  to 
map  your  task's  image  when  your  task  is  running  in  user  mode. 
Legal  values  are  0,  4,  and  5.  If  you  do  not  specify  n,  .he  Task 
Builder  assumes  a  value  of  5. 

If  you  do  not  explicitly  specify  that  your  task  is  to  run  on  a 
mapped  system  (through  the  /MM  switch)  and  it  is  not  otherwise 
implied  (TKB  is  not  running  in  a  system  with  KT-11  hardware),  TKB 
merely  tests  the  value  of  n  for  validity,  but  otherwise  ignores 
it. 


Default 

/-AC 


NOTE 


You  should  not  use  /AC  and   /PR 
same  command  line. 


the 
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AL 


10.1.2   /AL  —  Al'ocate  Checkpoint  Space 
File 

Task  image 
Syntax 

f ile.TSK/AL=f ile.OBJ 
Description 

The  /AL  switch  informs  TKB  that  your  task  is  checkpointable.  The 
system  will  checkpoint  it  to  a  space  in  your  task's  image  file. 
However,  the  system  uses  the  system  checkpoint  file  first  if  you 
specified  dynamic  checkpointing. 


Effect 


As  well  as  making  your  task  checkpointable,  this  switch  directs 
TKB  to  allocate  additional  space  in  your  task  image  file  to 
contain  the  checkpointed  task  image. 


Default 

/-AL 


NOTES 

Do  not  use  /CP  in  the  same  command 
in  which  you  use  /AL. 


1  ine 


Also,  the  /AL  switch  should  not  be  used 
with  the  /-HD  switch  to  build  tasks. 
Examples  of  tasks  that  use  the  /-HD 
switch  are:  the  Executive,  device 
drivers,  and  commons. 
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cc 


10.1.3   /CC  —  Concatenated  Object  Modules 
File 

Input 
Syntax 

f  1  le.TSK=f i le.OBJ/-CC 
Description 

/CC  controls  the  way  TKB  extracts  modules  from  your  input  file. 


Effect 


file 
Default 

/CC 


By  default,  TKB  includes  in  your  task's  image  all  the  modules  of 
your  input  file.  If  you  negate  this  switch  (as  in  the  Syntax 
section  above),  TKB  includes  only  the  first  module  of  your   input 
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CM 


10.1.4   /CM  —  Compatibility  Mode  Overlay  Structure 
File 

Task  image 
Syntax 

f i le.TSK/CM=f ile.OBJ 
Description 

/CM  causes  the  Taak  Builder  to  build  your  task   in   compatibility 
mode . 


Effect 


TKB  aligns  nemory-resident  overlay  segments  on  256-word 
boundaries  for  compatibility  with  other  implementations  of  the 
■napping  directives. 


Default 

/-CM 
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CO 


10.1.5  /CO  —  Build  a  Common  Block  Shared  Region 
File 

Task  image 
.STB  file 

Syntax 

file. TSK/CO=  file.  OBJ 
or 

,  ,f ile.STB/CO=f ile.OBJ 
Description 

The  /CO  switch  informs  TKB  that  a  shared  common  is  being  built. 
If  you  build  a  shared  common,  you  should  use  the  /CO  switch  and 
the  /-HD  switch. 

If  you  use  the  /-PI  switch  for  an  absolute  shared  common,  all  the 
program  sections  in  the  common  are  marked  absolute.  Using  the 
/-PI/-HD  switches  without  the  /CO  switch  causes  TKB  to  build  a 
shared  library. 

If  you  use  the  /PI  switch  for  a  relocatable  shared  common,  all 
program  sections  in  the  common  are  marked  relocatable. 

In  either  case,  the  .STB  file  contains  all  the  program  section 
names,  attributes,  length,  and  symbols.  TKB  links  common  blocks 
by  means  of  program  sections.  Therefore,  the  .STB  file  of  a 
shared  region  built  with  the  /CO  switch  contains  all  defined 
program  sections. 

Using  the  /PI/-HD  switches  without  the  /CO  switch  causes  TKB  to 
build  a  shared  common. 

The  /CO  switch  does  not  have  a  /-CO  form. 
Effect 

This  switch  causes  TKB  to  include  all  program  section 
declarations  in  the  .STB  file. 

Defaults 

/CO 
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CP 

10.1.6  /CP  —  Checkpointable 
rile 

Task  image 
Syntax 

file.TSK/CP=f i le.OBJ 
Description 

/CP  causes  TKB  to  mark  your  task  as  checkpointable.  The  system 
wil]  checkpoint  it  to  space  that  you  have  allocated  in  the  system 
chejkpoint  file  on  the  system  disk.  This  switch  assumes  that  you 
have  allocated  the  checkpoint  space  through  the  MCR  command  ACS. 
(Refer  to  the  RSX-llM/M-PLUS  MCR  Operations  Manual.) 


Effect 


The  system  writes  your  task  to  the  system  checkpoint  file  on 
secondary  storage  when  its  physical  memory  is  required  by  a  task 
of  higher  priority. 


Default 

/-CP 


NOTE 

Using    /AL    also   makes    your    task 
checkpointable . 
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CR 


10.1.7  /CR  —  Cross-Reference 
File 

Memory  allocation  (map) 
Syntax 

f  ile.TSK,f  ile.MAP/CP.=  f  ile.OBJ 
Description 

The  /CR  switch  directs  TKB  to  add  a   cross-reference   listing   to 
the  map  file  of  your  task. 

Effect 


TKB  creates  a  special  work  file  (file.CRF)  that  contains  segment, 
module,  and  global  symbol  information.  The  Task  Builder  then 
calls  the  Cross-Reference  Processor  (CRF)  to  process  the  file. 
CRF  creates  a  cross-reference  listing  from  the  information 
contained  in  the  file,  and  then  deletes  file.CRF.  (Refer  to  the 
RSX-11  Uti li t ies  Manual  for  more  information  on  CRF.) 


The  Example  section  below  describes  the 
and  its  contents. 


cross-reference   listing 


Default 

/-CR 
Example 


NOTE 

For  this  switch   to   be   effective,   CRF 
must  be  installed  in  your  system. 


Example  10-1  shows  a  cross-reference  listing  for  task  OVR.  The 
numbered  items  in  the  notes  correspond  to  the  numbers  in  Example 
10-1.  *^ 
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CR  (Cont.) 


Example    10-1      Cross-Reference    Listing    for    OVR.TSK 


CREF  CREATED    BY       TKB 

GLOBAL    CROSS    REFERErJCE 


ON  27-JUL-82  AT  09:46 


SYMBOL   VALUE 


AADD 

ADDEXI 

ARGBLK 

BUFF 

CALC 

DIFR 

DIVEXI 

DIVR 

DIVV 

I 

IE. EOF 

INITL 

INPUT 

lOSB 


020000-R 

020060-R 

001340-R 

001366-R 

003270-R 

001360-R 

020062-R 

001364-R 

020000-R 

001350-R 

177766 

005664-R 

003364-R 

001334-R 


REFERENCES. 


*  AADD 

*  AADD 
CALC 

*  MAIN 

*  CALC 
CALC 

*  DIVV 
CALC 

I?  CALC 
INPUT 
INPUT 

*  INITL 

*  INPUT 
INPUT 


8  CALC 

#  MAIN 
OUTPUT 

9  MAIN 

#  MAIN 


MAIN 

DIVV 

MAIN 

QIOSYM 

MAIN 

MAIN 

MAIN 


PAGE  1 
CREF    vol 


CREF        CREATED  BY   TKB     ON  27-JUL-82  AT  09:46 
SEGMENT  CROSS  REFERENCE 
SEGMENT  NAME   RESIDENT  MODULES 


PAGE  2 
CREF    vol 


AADD 

AADD 

CALC 

CALC 

DIVV 

DIVV 

INPUT 

ARITH 

CATB 

INPUT 

QIOSYM 

SAVRG 

LIBROT 

INITL 

SAVAL 

MAIN 

ALERR 
VCTDF 

AUTO 

MAIN 

OVCTR 

OVDAT 

MULL 

MULL 

OUTPUT 

ARITH 

CATB 

CBTA 

CDDMG 

C5TA 

EDTMG 

OUTPUT 

QIOSYM 

SAVRG 

SUBB 

SUBB 

Q 


OVRES    SAVRl 


DARITH   EDDAT 


NOTES 

The  cross-reference  page  header  gives  the  name  of  the   memory 

allocation   file,   the   originating   task  (TKB),  the  date  and 

time   the   memory   allocation   file   was  created,   and    the 
cross-reference  page  number. 

The  cross-reference  list  contains  an   alphabetic  listing   of 

each   global  symbol  along  with  its  value  and  the  name  of  each 

referencing  module.   When  a   symbol   is   defined  in   several 
segments   within  an  overlay  structure,  the  last  defined  value 

is  printed.   Similarly,  if  a   module   is   loaded  in   several 

segments   within   the  structure,  the  module  name  is  displayed 
more  than  once  within  each  entry. 
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CR  (Cont.) 


The  suffix  -R  appears  next  to  the   value   if   the   symbol   is 
relocatable . 

Prefix  symbols  accompanying  each  module  name  define  the   type 
of  reference  as  follows: 


Prefix  Symbol 
blank 


f 

I 


Reference  Type 

Module  contains  a  reference  that  is 
resolved  in  the  same  segment  or  in  a 
segment  toward  the  root. 

Module  contains  a  reference  that  is 
resolved  directly  in  a  segment  away  from 
the  root  or  in  a  co-tree. 


Module   contains   a    reference    that 
resolved  through  an  autoload  vector. 


1  s 


Module    contains 
det  ini  t  ion . 


a      nonautoloadable 
Module  contains  an  autoloadable  definition. 


Q  The  segment  cross-reference  lists  the  name  of  each  overlay 
segment  and  the  modules  that  compose  it.  If  the  task  is  a 
single-segment  task,  this  section  does  not  appear. 
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DA 

10.1.8      /DA   —    Debugging    Aid 
File 

Task    iinaqe    or    input 
Syntax 

f ile.TSK/DA=f ile.OBJ 

or 

file.TSK=£iIe .OBJ , f lie .OBJ/DA 

Description 

/DA  causes  TKB  to  include  a  debugging   aid   in   your   task.    The 
debugging  aid  controls  the  task's  execution. 


Effect 


If  you  apply  this  switch  to  your  task  image  file,  TKB  includes 
the  system  debugging  aid  LBO : [ 1 , 1 1 ODT. OBJ  into  your  task  image. 
If  you  use  the  /DA  switch  with  the  /ID  switch,  TKB  includes 
LB: (l,i]ODTID.OBJ  in  the  task. 

TKB  passes  control  to  the  debugging  program  when  you  or  the 
system  starts  task  execution. 

IE  you  apply  this  switch  to  one  of  your  input  files,  TKB  assumes 
that  the  file  is  a  debugging  aid  that  you  have  written.  Such 
debugging  programs  can  trace  a  task,  printing  out  relevant 
debugging  information,  or  monitor  the  task's  performance  for 
analysis.   The  default  file  typp  for  the  debugging  aid  is  .OBJ. 

In  either  case,  /DA  has  the  following  effects  on  your  task  image: 

•  The  transfer  address  of  the  debugging  aid  overrides  the 
task  transfer  address. 

•  TKB  initializes  the  header  of  your  task  so  that,  on 
initial  task  load,  registers  RO  through  R4  contain  the 
following  values: 

RO  -  Transfer  address  of  task. 

Rl  -  Task  name  in  Radix-50  format  (word  #1). 

R2  -  Task  name  ;word  #2) . 

R3  -  The  first  three  of  six  RAD50  characters  representing 
the  version  of  your  task.  TKB  derives  the  version 
from  the  first  .IDENT  directive  it  encounters  in  your 
task.  If  no  .IDENT  directive  is  in  your  task,  this 
valu'")  is  01. 

R4  -  The  second  three  RAD50  characters  representing  the 
version  of  your  task. 


Default 

/-DA 
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DL 


10.1,9   /DL  --  Default  Library 
File 

Input 
Syntax 

f i le.TSK=f i le.OBJ, tile.OLB/DL 

Descrip':ion 

This  switch  causes  the  input  file  to  be  i  replacement  for  tne 
system  object  module  library.  The  default  file  type  for  the 
input  file  is  .OBJ. 


Effect 


The  library  file  you  have  specified  replaces  the  file 
LBO: [ 1,11 SYSLIB.OLB  as  the  library  tile  that  the  Task  Builder 
searches  to  resolve  undeiined  global  references.  The  default 
device  for  the  replacement  file  is  SYO:.  TKB  refers  to  it  only 
when  undefined  symbols  remain  after  it  has  processed  all  the 
files  you  have  specified.  You  can  apply  the  /DL  switch  to  only 
one  input  file. 


Default 

/-DL 
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EA 

10.1.10   /EA  —  Extended  Arithmetic  Element  ^ 

File 

Task  image 
Syntax 

f ile.TSK/EA=f ile.OBJ 
Description 

/EA   informs   TKB   that   your   task   uses   the   KEll-A    Extended 
Arithmetic  Element. 


Effect 


s 
Default 

/-EA 


TKB  allocates  three  words  in  your  task's  header   for   saving   the 
state  of  the  extended  arithmetic  element. 


NOTE 

You  should  not  use  /EA  and   /FP  on   the 
same  command  line. 
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it 


10.1.11   /EL  --  Extend  Library 
File 

Task  image 
Syntax 

f i  le.TSK/LI/-HD/EL=f i le.OBJ 
Description 

/EL  places  the  upper  address  limit  as  determined  by  the  PAR 
option  in  the  library's  label  block,  though  the  actual  size  of 
the  library  may  be  smaller.  This  switch  is  useful  when  you  build 
vectored  libraries  such  as  RMS,  which  are  subject  to  size 
changes . 


Effect 


This  switch  specifies  the  maximum  possible  size  for  the  library 
according  to  the  size  specified  in  the  PAR  option.  The  switch 
specifies  a  larger  library  virtual  address  range  than  is  actually 
present  in  the  library  to  allow  RMS  to  map  its  vectored  library 
segments . 


Default 

/-EL 
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FP 


10.1.12   /FP  --  Floating  Point 
File 

Task  image 
Syntax 

f i le.TSK/FP=f ile.OBJ 
Description 

/FP  informs  TKB  that  your  task  uses  the  Floating  Point  Processor. 
Effect 

TKB  allocates  25  words  in  your  task's  header  for  saving  the  state 
of  the  Floating  Point  Processor. 

Default 

/-FP  on  RSX-llM  systems 
/FP  on  RSX-llM-PLUS  systems 

NOTES 

1.  You  should  not  use  /FP  and  /EA  on 
the  same  command  line. 

2.  The  /PP  switch  allocates  space  in 
the  task  header  to  save  the  floating 
point  status  if  your  task  is  context 
switched.  Therefore,  in  an  RSX-llM 
systrm,  if  a  task  that  uses  the 
Floating  Point  Processor  is  built 
without  the  /FP  switch,  the  task 
will  run  correctly  until  a  second 
task  that  uses  the  Floating  Point 
Processor  is  run.  Then  both  tasks 
will  either  crash  or  produce 
incorrect  results.  Fcr  information 
on  changing  the  Task  Builder's 
defaults,  refer  to  Appendix  F. 
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FU 


10.1.13   /FU  --  Pull  Search 
File 

Task  image 
Syntax 

file.TSK/FU»f ile.ODL/MP 
Description 

This  switch  controls  the   Task   Builder's   search   for   undefined 
symbols  when  it  is  processing  modules  from  the  default  library. 


Effect 


When  TKD  processes  modules  from  the  default  object  module 
library,  and  it  encounters  undefined  symbols  within  those 
modules,  it  normally  limits  its  search  for  definitions  to  the 
root  of  the  main  tree  and  to  the  current  tree.  Thus,  unintended 
global  references  between  co-tree  overlay  segments  are 
eliminated.  When  the  /FU  switch  is  appended  to  the  task  image 
file  of  an  overlaid  task,  TKB  searches  all  co-tree  segments  for  a 
matching  definition  or  reference.  See  Sections  3.2.2  and  3.2.3 
in  Chapter  3  for  more  details. 


Default 

/-FU 
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HD 

10.  1.14   /HD  --  Header 
File 

Task  image  or  symbol  definition 
Syntax 

f ile.TSK/-HD,,f ile,STB-f ile.OBJ 

or 

f i le.TSK, ,f i le.STB/-HD=f ile.OBJ 

Description 

The  /-HD  form  of  this  switch  directs  TKB  to  exclude  a  header  from 
your  task  image. 

Effect 

TKB  does  not  construct  a  header  in  your  task  image.  You  use  the 
negated  form  of  this  switch  when  you  are  building  commons, 
resident  libraries,  and  loadable  drivers. 


Default 
/HD 
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10.1.15   /ID  —  I-  and  D-space  Task  (RSX-llM-PLUS  Only) 
File 

Task  image 
Syntax 

f  i le . TSK/ 1 D- f  i le . OBJ 

Description 

This  switch  directs  TKB  to  mark  your  task  as  one  that  uses 
I-space  APRS  and  D-space  APRs  in  user  mode.  TKB  separates 
I-PSECTs  from  D-PSECTs. 


Effect 


TKB  includes  the  data  structures  in  the   task   label   block   that 
informs  INSTALL  that  the  task  has  separate  I-space  and  D-space. 


Default 

/-ID 
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IP 


10.1.16   /IP  —  Task  Maps  I/O  Page 
File 

Task  image 
Syntax 

f lie. TSK/PR/-1P= file. OBJ 
Description 


You  use  the  /-IP  switch  to  inform  TKB  that  the  task  is   purposely 
over  12K  and  does  not  need  to  be  mapped  to  the  I/O  page. 


Effect 


TKB  sets  a  bit  in  the  task's  label  block  that  informs  INSTALL 
(INS)  that  the  task  intentionally  does  not  map  the  I/O  page. 
When  this  bit  is  set,  INS  does  not  display  an  error  message  when 
it  detects  that  the  privileged  task  extends  into  APR  7. 


Default 

/IP 
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10.1.17   /LB  --  Library  File 
File 

Input 
Syntax 

f ile.TS K= file. OBJ, fi le.OLB/LB 
or 

f ile.TSK=f ile.OBJ,f ile.0LB/LB:mod-l:mod-2. . . :mod-8 
Description 

The  file  to  which  this  svntch  is  attached  is  an  object  module 
library  file.  The  Task  Builder's  interpretation  of  this  switch 
depends  upon  which  of  the  following  forms  you  use: 

•  Without  arguments  (the  first  syntax  given  above) 

•  With  arguments  (the  second  syntax  given  above) 
The  default  file  ty^^e  is  .OLB. 

Effect 

If  you  apply  this  switch  without  arguments,  TKB  assumes  that  your 
input  file  is  a  library  file  of  relocatable  object  modules.  TKB 
searches  the  file  immediately  to  resolve  undefined  references  in 
any  modules  preceding  the  library  specification.  It  also 
extracts  from  the  library,  for  inclusion  in  the  tasl<  image,  any 
modules  that  contain  definitions  for  such  references. 

If  you  apply  the  switch  with  arguments,   TKB   extracts  from   the 

library   the   modules  named  as  arguments  of  the  switch  r-^gardless 

of  whether  the  modules  contain  definitions  for  unresolved 
references . 

If  you  want  TKB  to  search  an  object  module  library  file  both  to 
resolve  global  references  and  to  select  named  modules  for 
inclusion  in  your  task  image,  you  must  name  the  library  file 
twice:  once,  with  the  modules  you  want  included  in  your  task 
image  listed  as  arguments  of  the  /LB  switch;  and  a  second  time, 
with  the  /LB  switch  and  no  arguments.   For  example: 


f ile.TSK= file. OLB/LB:mod-l :mod-2, file. OLB/LB 
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LB  (Cont.) 


The  position  of  the  library  file  within  TKB  command   sequence   is 
important.   The  following  rules  apply: 

•  The  library  file  must  follow  to  the  ricjht  of  the  input 
file(s)  that  contain  references  to  be  defined  in  the 
library.   For  example:  • 

TKB>L  1  lo.TSK=inf  i  lei.  5nj,  1  ih.OI.n/LD  ' 

The  command  above  illustrates  the  correct  usage  of  the   /LB 
switch;   the  following  command  illustrates  incorrect  usage: 

TKB>f i le.TSK  =  l ib.OLB/LH,f i lol  .OBJ 

•  If  you  are  using  the  Task  Builder's  multiline  input,  and 
you  specify  a  given  library  more  than  once  during  the 
command  sequence,  you  must  attach  the  /LB  switch  to  the 
library  file  each  time  you  specify  the  library.  For 
example: 

>TKW 

TKB>f  ile.TSK=fllel .ODJ,f i le2.0BJ, lib.OLB/LB 

TKB>f ile3.0BJ,f ile4.0BJ,lib.0LB/LB 

// 

•  When  you  are  building  an  overlay  structure,  you  must 
specify  object  module  libraries  for  an  overlay  structure 
within  the  Overlay  Description  Language  (ODL)  file  for  the 
structure.  To  do  this,  you  must  use  the  .FCTR  directive  to 
sp2cify  the  library.   For  example: 

CNTRL-LIB- (AFCTR,BFCTR,C) 
A0-LIB-(A1,A2- (A2l,A22) ) 
BO-LIB- (B1,B2) 
LB:  [303,31LIBOBJ.OLB/LB 


The  technique  used  in  the  ODL  file  above  allows  you  to  control 
the  placement  of  object  module  library  routines  into  the 
segments  of  your  overlay  structure.  (For  more  information  on 
overlaid  tasks,  see  Chapter  3.) 


NOTES 


1.  You  should  not  use  the  /LB  switch 
and  the  /CC  switch  in  the  same 
command  sequence. 

2.  You  can  use  the  /SS  switch  in 
conjunction  with  the  /LB  switch 
(with  or  without  arguments)  to 
perform  a  selective  search  for 
global  definitions. 


.ROOT 

AFCTR: 

.FCTR 

BFCTR: 

.FCTR 

LIB: 

.FCTR 

.END 

Default 

/-LB 
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LI 


10.1.18   /LI  —  Build  a  Library  Shared  Region 
File 

Task  image 
.STB  file 

Syntax 

file. TSK/LI-file. OBJ 
or 

,  ,f ile.STB/LI  =  f i le.OBJ 
Description 

The  /LI  switch  makes  TKB  build  a  shared  library.  However,  you 
must  use  the  /-HD  switch  with  the  /LT  switch  to  build  the  shared 
library.   The  /LI  switch  does  not  havt  a  /-LI  form. 

Effect 


TKB  includes  only  one  program  section   declaration 

file. 


in 


the 


,  STB 


If  you  use  the  /-PI  switch  for  an  absolute  library,  TKB  names  the 
program  section  .  ABS,  makes  the  library  position  dependent,  and 
defines  all  symbols  as  absolute.  Also,  if  you  use  tiie  /-PI 
switch  without  the  /LI  switch,  TKB  assumes  /LI  to  be  the  default. 

If  you  use  the  /PI  switch  for  a  relocatable  library,  TKB  names 
the  program  section  the  same  as  the  root  segment  of  the  library. 
TKB  forces  this  name  to  be  the  first  and  only  declared  program 
section  in  the  library.  TKB  declares  all  global  symbols  in  the 
.STB  file  relative  to  that  program  section.  Also,  if  you  use  the 
/PI  switch  without  the  /LI  switch,  TKB  assumes  that  a  shared 
common  is  to  be  built  (/CO  is  the  default). 


Default 


/-LI 
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10.1.19   /MA  --  Map  Contents  of  File 
File 

Input  or  memory  allocation 
Syntax 

f ile.TSK,f ile.MAP-f ile.OBJ,f ile.OBJ/-MA 

or 
f ile.TSK,f i le.MAP/MA=f ile.OBJ 
Description 

TKB  is  to  include  information  from  your  input  file  in  the  memory 
allocation  output  file. 

Effect 

If  you  negate  this  switch  and  apply  it  to  an  input  file,  TKB 
excludes  from  the  map  and  cross-reference  listings  all  global 
symbols  defined  or  referred  to  in  the  file.  In  addition,  TKB 
does  not  list  the  file  in  the  "file  contents"  section  of  the  map. 

If  you  apply  this  switch  to  the  map  file,  TKB  includes  in  the  map 
file  the  names  of  routines  it  has  added  to  your  task  from  SYSLIB. 
It  also  includes  in  the  map  file  information  contained  in  the 
symbol  definition  file  of  any  shared  region  to  which  the  task 
refers . 

Default 

/MA  for  input  files 

/-MA  for  system  library  and  resident  library  STB  files 
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10.1.20   /MM[:n]  —  Memory  Management 
Pile 

Task  image 
Syntax 

file. TSK/MM [ : n J  - f  i 1 e . OB J 
or 

file.TSK/-MM(:nl=flle.OBJ 
Description 

The  /MM  switch  informs  TKB  whether  the  system  on  which  your  task 
is  to  run  has  memory  management  hardware.  Specify  n  as  the 
decimal  numbers  28  or  30. 

Effect 

If  you  use  n  with  the  /-MM  switch  (for  an  unmapped  system),  n 
specifies  the  highest  physical  address  in  K-words  of  the  task  or 
system  being  built.  If  you  do  not  specify  n  with  /-MM,  the 
default  highest  address  of  the  task  or  system  is  28K. 

If  you  specify  n  with  /MM,  n  is  ignored. 

Default 

When  you  do  not  apply  /MM  or  /-MM  to  your  task  image  file,  TKB 
allocates  memory  according  to  the  mapping  status  of  the  system  on 
which  your  task  is  being  built.  The  maximum  task  size  for  a 
mapped  system  is  always  32K.  Tho  default  highest  address  for  a 
task  or  system  in  an  unmapped  system  is  28K. 

NOTE 

When   you   use   /-MM,   TKB    does    not    recognize  the 

memory-resident   overlay   operator(!).    TKB   checks  the 

operator  for  correct  syntax,  but  it  does  not   create  any 
resident  overlay  segments. 
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10.1.21   /MP  --  Overlay  Description 
File 

Input 
Syntax 

f ile.TSK»f ile.ODL/MP 
Description 


The  /MP  switch  specifies   that   the   input   file   is   an   Overlay 
Description  Language  (ODL)  file. 


Effect 


TKB  receives  all  the  input  file  specifications  from  this  file. 
It  allocates  virtual  address  space  as  directed  by  the  overlay 
description.  If  you  use  the  Task  Builder's  multiline  command 
format  (see  Section  1.3),  TKB  requests  option  information  at  the 
console  terminal  by  displaying: 

ENTER  OPTIONS  :  . 


NOTES 


1.  If  you  use  the  multiline  command 
format  when  you  specify  an  ODL  file, 
TKB  automatically  prompts  for  option 
input.  Therefore,  you  must  not  use 
the  single  slash  (/)  to  direct  TKB 
to  switch  to  option  input  mode  when 
you  have  specified  /MP  on  your  input 
file. 

2.  When  you  specify  /MP  on  the  input 
file  for  your  task,  it  must  be  the 
only  input  file  that  you  specify. 
The  default  file  type  is  .ODL. 


Default 

/-MP 
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10.1.22   /MO  —  Multiuser  (RSX-llM-PLOS  Only) 
Pile 

Input 
Syntax 

file.TSK/MU- file. OBJ 
Description 

The  /MU  switch  specifies  to  TKB  that   the   task   is   a   multiuser 
task . 


Effect 


TKB  separates  your  task's  read-only  and  read/write  program 
sections.  It  then  places  the  read-only  program  sections  in  your 
task's  upper  virtual  address  space  and  the  read/write  program 
sections  in  your  task's  lower  virtual  address  space. 


Default 

/-MU 
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NM 


10.1.23  /NM  —  No  Piagnostic  Messages 
File 

Task  image 
Syntax 

flle.TSK/NM-f ile.OBJ 
Description 

The  /NM  switch  controls  the  printing  of  diagnostic  messages. 
Effect 

This  switch  eliminates  two  messages: 
n  Undefined  symbols  segment  seg-name 

and 

Module  module-name  multiply  defines    P-section   p-sect-name 
Default 

/-NM 


e 
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10.1.24   /PI  —  Position  Independent 
File 

Task  image  or  symbol  definition 
Syntax 

f ile.TSK/PI-f ile.OBJ 
or 

file.TSK,, file. STB/PI -file. OB J 
Description 

/PI  informs  TKB  that  the  task's  shared  region  contains  only 
position-independent  code  or  data.  Use  this  switch  with  /-HD  and 
either  /CO  or  /LI. 


Effect 


TKB  sets  the  position-independent  code  (PIC)  attribute  flag  in 
the  label  block  flag  word  of  the  shared  region. 

Be  aware  that  if  you  specify  /PI  without  using  the  /CO  or  /LI 
switches,  TKB  builds  a  shared  common  (/CO  default).  Also,  if  you 
specify  /-PI  without  using  the  /CO  or  /LI  switch,  TKB  builds  a 
shared  library  (/LI  default). 


Default 

/-PI 
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10.1.25  /PM  —  Postmortem  Dump 
File 

Task  image 
Syntax 

file. TSK/PM-file. OBJ 

Description 

If  you  use  /PM  and  your  task  terminates   abnormally,   the   system 
automatically  lists  the  contents  of  the  memory  image. 

Effect 

TKB  sets  the  Postmortem  Dump  flag  in  your  task's  label  flag  word. 

NOTES 

1.  If  your  task  issues  an  ABRT$  (abort 
task)  directive,  the  system  will  not 
dump  the  task  image  even  though  TKB 
has  set  the  Postmortem  Dump  flag  in 
your  task's  label  flag  word.  In 
this  case,  the  system  assumes  that  a 
Postmortem  Dump  is  not  necessary 
since  you  know  why  your  task  was 
aborted . 

2.  The  PMD  utility  must  be  installed  in 
your  system  and  be  able  to  get  into 
physical  memory  for  this  switch  to 
be  effective. 

Default 

/-PM 


10-32 


SWITCHES 


PR 


10.1.26   /PR(:n) 
File 


Privileged 


Task  image 

Syntax 

f ile.TSK/PR:0»f ile.OBJ 

oc 

f ile.TSK/PR:4»f ile.OBJ 

or 

f ile.TSK/PR:5=f ile.OBJ 

Description 

The  /PR  switch  informs  TKB  that  your  task  is  privileged  with 
respect  to  memory  and  device  access  rights.  If  you  specify  PR:0, 
your  task  does  not  have  access  to  the  I/O  page  or  the  Executive. 
However,  if  you  specify  PR:4  or  PR:5,  your  task  does  have  access 
to  the  I/O  page  and  the  Kxecutive,  in  addition  to  its  own 
par ti  t ion. 


Effect 


TKB  sets  the 
flag  word. 


Privileged  Attribute  flag  in  your  task's  label  block 


The  value  of  n  is  an  octal  number  that  specifies  the  first  Active 
Page  register  that  you  want  the  Executive  to  use  to  map  your  task 
image  when  your  task  is  running  in  user  mode.  Legal  values  are 
0,  4,  and  5.  If  you  do  not  specify  one  of  these  values,  TKB 
assumes  a  value  of  5. 

If  you  do  not  explicitly  specify  that  your  task  is  to  run  on  a 
mapped  system,  (through  the  /MM  switch)  and  it  is  not  implied  (by 
the  presence  of  KT-11  hardware  on  the  system  upon  which  TKB  is 
running),  TKB  merely  tests  the  value  (:n)  of  the  switch  for 
validity;  otherwise,  TKB  ignores  it.  Privileged  tasks  are 
described  in  Chapter  9. 


Default 


/-PR 


NOTE 

You  should  not  use  /PR  and 
same  command  line. 


/AC   on   the 
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10.1.27  /RO  --  Resident  Overlay 
Pile 

Task  image 
Syntax 

f lie. TSK/-RO- file. ODL/rtP 
Description 

The  Task  Builder's  recognition   of   the   memory-resident   overlay 
operator  (1)  is  enabled. 


Effect 


The  memory-resident  overlay  operator  (!),  when  present  in  the 
overlay  description  file,  indicates  to  TKB  that  it  is  to 
construct  a  task  image  that  contains  one  or  more  memory-resident 
overlay  segments.  If  you  negate  this  switch  (as  in  the  Syntax 
section  above),  TKB  checks  the  operator  for  correct  syntactical 
usage,  but  otherwise  ignores  it.  With  the  memory-resident 
overlay  operator  thus  disabled,  TKB  builds  a  disk-resident 
overlay  from  the  overlay  description  file. 


Default 
/RO 
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10.1.28   /SE  —  Send 
?ile 

Task  image  ^ 

Syntax  /^ 

f ile.TSK/-SE-f ile.OBJ 

Description 

T^is  switch  determines  whether  messages  can  be  directed  to  your 
t.  sk  by  means  of  the  Executive  Send  directive.  (Refer  to  the 
RSX-11M/M-PL.US  Executive  Reference  Manual  for  information  on  the 
Send  directive) 


Effect 


By  default,  messages  can  be  directed  to  your  task  by  means  of  the 

Executive   Send   directive.   If  you  negate  this  switch  (as  in  the 

Syntax   section   above),   the   system   inhibits   the   queuing  of 
messages  to  your  task. 


Default 

/SE 
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10.1.29   /SG  —  Segregate  Program  Sections 
File 

Task  image 
Syntax 

f i le.TSK/SG=f ile.OBJ 
Description 

The  /SG  switch   allocates   virtual   address   space   to   all   (RW) 
program  sections  and  then  to  all  read-only  (RO)  pro.ji  im  sections. 


Effect 


The  /SC  switch  gives  you  control  over  tho  ordering  of  program 
sections.  By  using  the  /SG  switch,  you  cause  TKB  to  order 
program  sections  alphabet ical ly  by  name  within  access  code  ( RW 
followed  by  RO) .  If  you  specify  the  /SQ  switch  with  the  /SG 
switch,  TKB  orders  program  sections  in  their  input  order  by 
access  code.   See  the  description  of  the  /SQ  switch. 

You  use  the  negated  switch,  /-SG,  to  make  TKB  interleave  the  RW 
and  RO  program  sections.  Thus,  the  combination  /-SG/SQ  results 
in  a  task  with  its  program  sections  allocated  in  input  order  and 
Its  RW  and  RO  sections  interleaved.  Additionally,  you  can  use 
/-SQ/-SG  to  make  TKB  order  program  sections  alphabetically  with 
RW  and  RO  sections  interleaved.   However,  /-SG  is  the  default. 

When  taskbuilding  multiuser  tasks,  the  /MU  switch  causes  TKB  to 
default  to  /SG.  Therefore,  to  correctly  build  read-only  tasks, 
you  can  use  the  /MU  switch  only. 


Default 

/-SG 
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10.1.30   /SH  --  Short  Map 
File 

Memory  allocation  (map) 
Syntax 

file.TSK,file.MAP/SH»file.OBJ 
Deacrxotion 

If  you  specify  /SH,  TKB  produces  the  short  version  of  the  memory 
al locat  ion  f i le. 

Effect 

TKB  does  not  produce  the  "file  contents"  section  of  the  memoiv 
allocation  file. 

Default 

/SH 

Example 

The  memr ry  allocation  file  consists  of  the  following  items: 

•  P^ge  header 

•  Task  attributes  section 

•  Overlay  description  (if  applicable) 

•  Root  segment  allocation 

•  Tree  segment  description  (if  applicable) 

•  Undefined  references  (if  applicable) 

•  Task  Builder  statistics 

An  example  of  the  memory  allocation  file  (map)  is  shown  in 
Example  10-2.  The  numbered  and  lettered  items  in  the  notes 
cotrespond  to  the  numbers  and  letters  in  Example  10-2. 


Example  10-2   Memory  Allocation  File  (Map)  Example 


OVR.TSK;!     Memory  Allocation  Map   TKB  M40.10       Page  1 

15-DEC-82    11:28 


Jo 


Partition  name  •  GEN  a:  (F' 

Identification  :  01  c 

Task   UIC       :  [303,3]  d   e 

Stack     limits:  000260  001257  001000  00512.  f 


(continued  on  next  page) 
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Example  10-2  (Cont.)   Memory  Allocation  File  (Map)  Example 


9tq    xfr  address:  001264  Q    (ii)  CI) 

Total  address  windows:  1.  I   k   i 

Task   i-naqe   size   :  7488.  words  m   n 

Task  address  limits:  000000  035107  o 

R-W  disk  blk  limits:  000002  000073  000072  00058.  P'  (q> 

OVR.TSK  Overlay  description: 


Base 

000000 
005034 
005034 
021060 
021060 

OVR.TSK 
ROOTM 


Top 

005033 
021057 
021057 
035103 
035107 


Length 


005034 
014024 
014024 
014024 
014030 


02588. 
06164. 
0616'"  . 
06164. 
06168. 


ROOTM 
MULOV 
AD30V' 
SUBOV 
DIVOV 


Memory  allocation  map   TKB  M40.02 
28-DEC-81    09:10 


***  Root  segment:  ROOTM  » 

R/W  mem   limits:  000000  005033  005034  02588.(1) 
Disk  blk  limits:  000002  000007  000006  00006. 'o) 

Memory  allocation  synopsis: 


Sect  ion 


BLK. : (RW, I,LCL,REL,CON) 


ANS 


(RW,D,GBL,REL,OVR) 


001260  002514  01356. 
001260  000102  00066. 
001361  000260  00176. 
001642  000042  00034. 
003774  000002  00002. 
003774  000002  000002, 
003774  000002  00002. 
003774  000002  00002. 


Global  Symbols: 
AADD    004032-R 


Page  2 


ROOTM 
PRNOV 
SAVOV 


ROOTM 
PRNOV 


01 
01 
01 


01 
01 


Title   Ident   File 


ROOTM. OB J, -1 
PRNOV. OBJ ;1 
SAVOV. OBJ ;1 


ROOTM. OBJ; 1 
PRNOV. OBJ ;1 


004042-R  '») 


OVR.TSK 
MULOV 


DIVV    004052-R   PRINT   001550-R   SUBB 
MULL    004022-R   SAVAL   001642-R 

9   h  *'   yi)   (i) 
Memory  allocation  map   TKB  M40.02  Page  3 
28-DEC-81    09:10 


o 


Segment:  MULOV 


R/W  mem   limits:  005034  021057  014024  06164. 
Disk  blk  limits:  000010  000024  000015  00013. 


(continued  on  next  page) 
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Example  10-2  (Cont.)   Memory  AUocstlon  File  (Map)  Example 


Memory  allocation  aynopaist 
Section 


.  BLK. : (RW, I,LCL,REL,CON)  OOSO?*  014024  06164. 

005034  014024  06164, 

5$ALVC:  (RW,t),[,C[,,REL,CON)  021060  000000  00000. 

$$RTS  :  (RW,  I,BGL,REL,OVR)  004250  000002  00002. 


Global  symbols: 
MULL    021034-R 


Title   Ident  File 


MULOV   01     MUL0V.0BJ;1 


***  Task  builder  statistics: 

Total  work  file  references:  7156.  » 

Work   file   reads:  O.i 

Work   file  writes:  0.(  ''  ' 

Size  of  core  pool:  7086.  words  (27.  pages)  d 

Size  of  work  file:  3072.  words  (12.  pages)  , 

ELAPSED  TIME:00 :00 : 14 


Notes: 


O  The  page  header  shows  the  name  of  the  task  image  file  and  the 
overlay  segment  name  (if  applicable),  along  with  the  date, 
time,  and  version  of  TKB  that  created  the  map. 

O  The  task  attributes  section  contains  the  following 
informat  ion : 

(J)  Task  name  --  The  name  specified  in  the  TASK  option.  If 
you  do  not  use  the  TASK  option,  TKB  suppresses  this 
field. 

b  Partition  name  --  The  partition  specified  in  the  PAR 
option.  If  you  do  not  specify  a  partition,  the  default 
is  partition  GEN. 

(c)  Identification  --  The  task  version  as  specified  in  the 
.IDENT  assembler  directive.  If  you  do  not  specify  the 
task  identification,  the  default  is  01. 

(d)  Task  UIC  —  The  task  UIC  as  specified  in  the  UIC  option. 
If  you  do  not  specify  the  UIC,  the  default  is  the 
terminal  UIC. 
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(Tt  Task  priority  —  The  priority  of  the  task  as  specified  In 
the  PRI  option.  if  you  do  not  specify  PRI,  the  defa'jlt 
is  SO,  and  is  not  shown  on  the  map. 

(f  Stack  limits  --  The  low  and  hiqh  octal  addresses  of  the 
stack,  followed  by  its  length  in  octal  and  decimal  bytes. 

g  ODT  transfer  address  --  The  starting  address  of  the  ODT 
debugging  aid.  If  you  do  not  specify  the  ODT  debugging 
aid,  this  field  Is  suppressed. 

(h  Program  transfer  address  --  The  address  of  the  symbol 
specified  in  the  .END  directive  of  the  source  code  of 
your  task.  If  you  do  not  specify  a  transfer  address  for 
your  task,  TKB  automatically  establishes  a  tranfer 
address  of  OOOOOl  for  it.  TKB  also  suppresses  this  field 
in  the  map  if  you  do  not  specify  a  transfer  address. 

fl  Task  attributes  --  These  attributes  are  listed  only  if 
they  differ  from  the  defaults.  One  or  more  of  the 
following  may  be  displayed: 

AC     Ancillary  control  processor. 

AL     Task  is  checkpointable,   and   task   image   file 
contains  checkpoint  space  allocation. 

CP     Task  is  checkpointable,   and   task   image   file 
will  be  checkpointed  to  system  checkpoint  file. 

DA  Task  contains  debugging  aid. 

BA  Task  uses  KEll-A  extended  arithmetic  element. 

fP  Task  uses  Floating  Point  Processor. 

-HD  Task  image  does  not  contain  header. 

PI     Task   contains   position-independent   code   and 
data . 

PM     Postmortem   Dump   requested   in   the   event   of 
abnormal  task  termination. 

PR     Task  is  privili-ged. 

-£^     Messages  addressed  to  the  task  t-hrough  the  SEND 
directive  will  be  rejected  by  the  Executive. 

SL      Task  can  be  slaved. 

TR     Task  initial  PS  word  has  T-bit  enabled. 

ID     Task  is  I-  and  D-space  task. 

0  Total  address  windows  --  The  number  of  window  blocks 
allocated  to  the  task. 


10-40 


SWITCHES 


SH  (Cont.) 


®  Napped  array  --  The  amount  of  physical  memory  (decimal 
words)  allocated  through  the  VSECT  option  or  Mapped  Array 
Declaration  (GSD  type  7,  described  in  Appendix  B) ; 
mapped  array  is  not  shown  if  it  does  not  apply. 

0   Task   extension  --  Tho   increment   of  physical  memory 

(decimal   words)   allocated   through  the   EXTT5;K  or  PAR 

option.   Without  these  options,   task  extension  is   not 
shown . 

(jwi  Task  image  size  --  The  amount  of  memory  (decimal  words) 
required  to  con'ain  your  task's  code.  This  number  does 
not  include  physical  memory  allocated  through  the  EXTTSK 
opt  ion. 

(n)  Total  task  size  --  The  amount  of  physical  memory  (decimal 
words)  allocated,  including  mapped  array  area  and  task 
extension  area.  Total  task  "jize  is  not  shown  in  this 
example. 

o  Task  address  limits  --  The  lowest  and  highest  virtual 
address'^s  allocated  to  the  task,  exclusive  of  virtu.il 
addresses  allocated  to  VSECTs  and  shared  regions. 

Tp"  Read/write  disk  block  limits  --  From  left  to  right:  the 
first  octal  relative  disk  block  number  of  the  task's 
header;  the  last  octal  relative  disk  block  number  of  the 
task  image;  and  the  total  contiguous  disk  blocks 
required  to  accommodate  the  read/write  portion  of  the 
task  image  in  octal  and  decimal. 


e 


fq'  Read-only  disk  block  limits  --  From  left  to  right:  the 
first  octal  relative  disk  block  of  the  multiuser  task's 
read-only  region;  the  last  octal  relative  disk  block 
number  of  the  read-only  region;  and  the  total  contiguous 
disk  blocks  required  to  accommodate  the  read-only  region 
in  octal  and  decimal.  This  field  appears  only  when  you 
are  building  a  multiuser  task. 

The  overlay  description  shows,  for  each  overlay  segment  in 
the  tree  structure  of  an  overlaid  task,  the  beginning  virtual 
address  (the  base),  the  highest  virtual  address  (the  top), 
the  length  of  the  segment  in  octal  and  decimal  bytes,  and  the 
segment  name.  indenting  is  used  to  illustrate  the  ascending 
levels  in  the  overlay  structure.  TKB  prints  the  overlay 
description  only  when  an  overlaid  task  is  created. 


O   The  root  segment  allocation 
elements  : 


--  This  section  has  the  following 


Root  segment  --  Th -^  name  of  the  root  segment.  If  your 
task  is  a  single-segment  task,  the  entire  task  is 
considered  to  be  the  root  segment. 


Read/write  memory  limits  --  From  left  to  right:  the 
beginning  virtual  address  of  the  root  segment  (the  base); 
the  virtual  address  of  the  last  byte  in  the  segment  (the 
top) ;  and  the  length  of  the  segment  in  octal  and  decimal 
bytes . 
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(o)  Dlik  block  limits  --  From  left  to  right:  the  first 
relative  block  number  of  the  beginnint)  o.  the  root 
segment;  the  last  rt'lative  block  number  of  the  root 
segment;  total  number  of  disk  blocks  in  octal;  and  the 
total  number  of  disk  blocks  in  decimal. 

(d  Memory  allocation  synopsis  --  From  left  to  right:  the 
program  section  name;  tht  ^.ogram  section  attributes; 
starting  virtual  address  of  the  program  section;  and 
total  length  of  the  program  section  in  octal  and  decimal 
bytes. 

The  program  section  shown  as  .  BLK.  in  this  field  is  the 
unnamed  relocatable  program  section.  Notice  in  this 
example  that  there  are  636(octal)  bytes  allocated  to  it 
(2034  bytes  -  1176  bytes  =  636  bytes).  This  allocation 
is  the  result  of  call?  to  routines  that  reside  within  the 
unnamed  program  section  in  SYSLIB.  (For  more 
information,  se<?  the  description  of  the  /MA  switch  in 
Section  10.1.14.) 

(?)  Module  contributor  --  This  field  lists  the  modules  that 
have  contributed  to  each  program  section.  In  this 
example,  the  program  section  ANS  was  defined  in  mc  lule 
ROOTM.  The  module  version  is  01  (as  a  result  of  the 
. IDENT  assembler  directive)  and  the  file  name  from  which 
the  module  was  extracted  is  ROOTM. OBJ; 1.  'f  the  program 
section  ANS  had  been  defined  in  more  than  ont  module, 
each  contributing  module  and  the  file  from  which  it  was 
extracted  would  have  been  listed  here. 


shown  because 
always  has  a 


(J)  The  global  symbols  section  lists  the  global  symbols 
defined  in  the  segment.  Each  symbol  is  listed  along  with 
its  octal  value.  A  -R  is  appended  to  the  value  if  the 
symbol  is  relocatable.  The  list  is  alphabetized  in 
columns . 

The  file  contents  section  (which   is   composed   of   the   four 

fields   listed   below)  is  printed  only  if  you  specify  /-SH  in 

the  TKB  command  sequence.  TKB  creates  this  section  for   each 

segment   in   an   overlay  structure.    It  lists  the  following 
information: 

[g  Input  file  --  File  name,  module  name  as  established  by 
the  .TITLE  assembler  directive,  and  module  version  as 
established  by  the  .IDENT  assembler  directive. 

(h)  Program  section  --  Program  section  name,  starting  virtual 
address  of  the  program  section,  ending  virtual  address  of 
the  program  section,  and  length  in  octal  and  decimal 
bytes. 
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®  Global  symbol  --  Glob.jl  symbol  namos  within  each  program 
section  anil  their  octal  values.  If  the  segment  is 
autoloadable  (see  Chapter  3),  this  value  in  the  address 
of  an  autoload  vector.  The  autoload  vector  In  turn 
contains  the  actual  address  of  the  symbol, 

A   -R   is   ippended   to   the   value   if   the   symbol    Is 
relocatable. 

r   Program  section  —  The   contents   of   this    field    is 
described  in  note  g  above. 

(K)  Undefined  References  --  This  field  lists  the  undefined 
global  symbols  in  the  segment. 

0  The  tree  segment  description  is  printed  for  every  overlay 
segment  in  an  overlay  structure.  Its  contents  are  the  same 
for  each  overlay  segment  as  the  root  segment  allocation  is 
for  the  root  segment. 

O  Task  builder  statistics  lists  the  following  information, 
which  can  be  used  to  evaluate  TKB  performance: 

a   Work  file  references  --  The   number   of   times   that   TKB 
accessed  data  stored  in  its  work  file. 

(b)  Work  file  reads  --  The  number  of  times  th.T.  the  work  file 
device  was  accessed  to  read  work  file  data. 

(c)  Work  file  writes  --  The  number  of  times  that  the  work 
file  device  was  accessed  to  write  work  file  data. 

(d)  Size  of  pool  —  The  amount  of  memory  that  was  a.ailable 
for  work  file  data  and  table  storage. 

(i)  Size  of  work  file  --  The  amount  of  device  storcigo  ••hat 
was  required  "-o  contain  the  work  file. 

(J)  Elapsed  time  --  The  amount  of  wall-clock  time  required  to 
construct  the  task  image  and  produce  the  memory 
allocation  (map)  file.  Elapsed  time  is  measured  from  the 
completion  of  option  input  to  the  completion  of  map 
outp:t.  This  value  excludes  the  time  required  to  process 
the  overlay  description,  parse  the  list  of  input  file 
names,  and  create  the  cross-reference  listing  (if 
speci  f ied) . 

See  Appendix  F  for  a  more  detailed  discussion  of  the  work  file. 


10-43 


SWITCHES 

SL 

10.1.31   /SL  --  Slave 
File 

Task  image 
Syntax 

file. TSK/SL=file. OBJ 

Description 

This  switch  directs  TKB  to  mark   your   task   as   a   slave   to   an 
initiating  task. 


Effect 


TKB  attaches  the  slave  attribute  to  your  task.  When  your  task 
successfully  executes  a  Receive  Data  directive,  the  system  gives 
the  UIC  a.id  TI  :  device  of  the  sending  task  to  it.  The  slave 
task  then  assumes  the  identity  and  privileges  of  the  sending 
task . 

This  switch  only  applies  to  your  task  if  the  system  that  you  are 
using  has  multiuser  protection.  (Refer  to  your  system  generation 
manual  for  more  information  on  multiuser  protection  and  slave 
tasks  . ) 


Default 


/-SL 
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10.1.32   /SP  --  Spool  Map  Output 
File 

Memory  allocation  (map) 
Syntax 

f ile.TSK,f ile.MAP/-SP=f ile.OBJ 
Description 

This  switch  determines  whether  TKB  calls   the   print   spooler   to 
spool  your  memory  allocation  (map)  file  after  task  build. 


Effect 


By  default,  when  you  specify  a  map  file  in  a  TKB  command 
sequence,  TKB  creates  a  map  file  on  device  SYO:  and  then  has  the 
file  queued  for  listing  on  LPO :  . 

If  you  negate  this  switch  (as  shown  in  the  Syntax  section  above), 
TKB  creates  the  map  file  on  de^'ice  SYO:  but  does  not  call  the 
print  spooler  to  output  it  to  LPO: 


Default 

/SP 


NOTE 

The   PRT   task   must   be   installed    to 
process  the  request  to  print  the  map. 
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10.1.33   /SQ  —  Sequential 
File 

Task  image 
Syntax 

file.TSK/SQ=f ile.OBJ 

Description 

This  switch  causes  TKB  to  construct   your   task   image   from   the 
program  sections  you  specified,  in  the  order  that  you  input  them. 


Effect 


If  you  use  this  switch,  TKB  collects  all  the  references  to  a 
given  program  section  from  your  input  object  modules,  groups  them 
according  to  their  access  code  (RW  followed  by  RO)  and,  within 
these  groups,  allocates  memory  for  them  in  the  order  that  you 
input  them.  However,  the  /SG  switch  affects  program  section 
ordering  and  can  be  used  with  the  /SQ  switch.  See  the  /SG  switch 
for  further  details. 

Without  the  /SQ  switch,  TKB  reorders  the  program  sections 
alphabetically. 

You  use  this  switch  to  satisfy  any   adjacency   requirements   that 

existing   code   may  have  when  you  are  converting  it  to  run  under 

RSX-11.  Using  this  feature  is  otherwise  discouraged  for  the 
following  reasons: 

•  Standard   library   routines   (such   as   FORTRAN   I/O  handling 
routines  and  FCS  modules  from  SYSLIB)  do  not  work  properly. 

•  Sequential  allocation  can  result  in  errors  if   you   alter   the 
order  in  which  modules  are  linked. 

Alternatively,  you  can  achieve  physical  adjacency  of  program 
sections  by  selecting  names  alphabetically  to  correspond  to  the 
desired  order. 


Default 

/-SQ 
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10.1.34   /SS  —  Selective  Search 
File 

Input 
Syntax 

fi3.e.TSK=f  ile.OBJ,f  ile.OBJ/SS 

or 
file.TSK=file.OBJ,f ile.STE/SS 

or 

file.TSK=fiIe.OBJ,f ile.OLB/LB/SS 

Description 

The  /SS  switch  directs  TKB  to  include  in  its  internal  symbol 
table  only  those  global  symbols  for  which  there  is  a  previously 
undefined  reference. 

Effect 

Whe  1  processing  an  input  file,  TKB  normally  includes  in  its 
internal  symbol  table  eacn  global  symbol  it  encounters  within  the 
file  whether  or  not  there  are  references  to  it.  With  the  /SS 
switch  attached  to  an  input  file,  TKB  checks  each  global  symbol 
it  encounters  within  that  file  against  its  list  of  undefined 
references.  If  TKB  finds  a  match,  it  includes  the  symbol  in  its 
symbol  table. 

Default 

/-SS 

Example 

Assume  that  you  are  building  a  task  named  SEL.TSK.  The  task  is 
composed  of  input  files  containing  global  entry  points  and 
references  (calls)  to  them  as  shown  in  Table  10-2. 

Table  10-2 
Input  Files  for  SEL.TSK 


Input 
File  Name      Global  Definition     Global  Reference 


INI 

A 
IN2  B 

C 
IN3 
IN4  A 

B 

C 
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File  IN2  and  IN4  contain  global  symbols  of  the  same  name  that 
represent  entry  points  to  different  routines  within  their 
respective  files.  Assume  that  you  want  TKB  to  resolve  the 
reference  to  global  symbol  A  in  INI  to  the  definition  for  A  in 
IN2.  Assume  further  that  you  want  TKB  to  resolve  the  reference 
to  global  symbol  C  in  IN3  to  the  definition  for  C  in  IN4.  By 
selecting  the  sequence  of  the  input  files  properly  and  applying 
the  /SS  switch  to  files  IN2  and  IN4,  TKB  resolves  the  references 
correctly.  The  following  command  sequence  illustrater  the 
correct  sequence: 

TKB>SEL.TSK=IN1.0BJ,  IN2.0BJ/SS,  IN  3.  OB  J,  IN4.0BJ/S.S 

TKB  processes  input  files  from  left  to  right;  therefore,  in 
processing  the  above  command  sequence,  TKB  processes  file  INI 
first  and  encounters  the  reference  to  symbol  A.  There  i  no 
definition  for  A  within  INI;  therefore,  TKB  marks  A  as  undefined 
and  moves  on  to  process  file  IN2.  Because  the  /SS  switch  is 
attached  to  IN2,  TKB  limits  its  search  of  IN2  to  symbols  it  has 
previously  listed  as  undefined,  in  this  case,  symbol  A.  TKB 
finds  a  definition  for  A  and  places  A  in  its  symbol  table. 
Because  there  are  no  undefined  references  to  symbols  B  or  C,  TKB 
does  not  place  either  of  these  symbols  in  its  symbol  table. 

NOTE 

It  is  important  to  realize  that  the  /SS 
switch  affects  only  the  way  the  Task 
Builder  constructs  its  internal  symbol 
table.  The  routines  for  which  symbols  B 
and  C  are  entry  points  is  included  in 
the  task  image  even  though  there  are  no 
references  to  them. 


TKB  moves  on  to  IN3.   It  encounters  the  references  to  symbol   C. 

Because   TKB   did   not   include   symbol   C  from  IN2  in  its  symbol 

table,  it  cannot  resolve  the  reference  to  C  in  IN3.  TKB  marks 
symbol  C  as  undefined  and  rr^ves  en  to  IN4, 

When  TKB  processes  IN4 ,  it  encounters  the   definition   for   C   in 

that   file   and   includes  it  in  the  table.   Again,  since  the  /SS 

switch  is  attached  to  IN4,  TKB  includes  only  C  in  its  symbol 
table. 

When  TKB  has  completed  its  processing  of  the  above  command 
sequence,  it  has  constructed  a  task  image  composed  of  all  of  the 
code  from  all  of  the  modules,  INI  through  IN4.  However,  only 
symbols  A  from  IN2  and  C  from  IN4  will  appear  in  its  internal 
symbol  table. 
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NOTE 

The  example  above  does  not  represent 
good  programming  practice.  It  is 
included  here  to  illustrate  the  effect 
of  the  /SS  switch  on  TKB  during  a  search 
sequence. 


The  /SS  switch  is  particularly  valuable  when  used  to  limit  the 
size  of  the  Task  Builder's  internal  symbol  table  during  the 
building  of  a  privileged  task  that  references  the  Executive's 
routines  and  data  structures.  By  specifying  the  Executive's 
Symbol  Definition  File  (STB)  as  an  input  file  and  applying  the  SS 
switch  to  it,  TKB  includes  in  its  internal  symbol  table  omy 
those  symbols  in  the  Executive  that  the  task  references.  An 
example  of  a  TKB  command  sequence  that  illustrates  this  is  shown 
below: 

TKB>OUTFILE.TSK/PR: 5= TNF  H.K . OB J , RSXl IM  ,  STB/SS 


The  above  command  sequence  directs  TKB  to  build 

named    OUTFILE.TSK    from    the    input  file 

specification  of  the  Executive's  STB  file  as  an 

the   SS   switch   applied   to   it   directs  TKB 

RSXllM.STB  only  those  symbols   for   which  .here 
within  OUTFILE.TSK. 


a  privileged  task 
INFILE.OBJ.  The 
input  file  with 
to  extract  from 
are   references 
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10.1.35   /TR  --  Traceable 
File 

Task  image 
Syntax 

f ile.TSK/TR=f ile.OBJ 
Description 

This  switch  directs  TKB  to  make  your  task  traceable. 
Effect 

TKB  sets  the  T-bit  in  the  initial  PS  word  of  your  task.  When 
your  task  is  executed,  a  trace  trap  occurs  when  each  instruction 
is  completed. 

Default 

/-TR 
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10.1.36   /WI  —  Wide  Listing  Format 

File 

Memory  allocation  (map) 

Syntax 

f ile.TSK,f ile.MAP/-WI=f ile.OBJ 

Description  '  ; 

This  switch  controls  the  width  of  your  map  file. 

Effect- 
By  defaull,  TKB  formats  a  map  file  132  columns   wide.    When   you 
negate   this  switch  (as  in  the  Syntax  section  above),  TKB  formats 
the  map  file  80  columns  wide. 

Default 
/WI 
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10.1.37   /XH  —  External  Header  (RSX-llM-PLUS  only) 

File 

Task  image 

Syntax 

;     file.TSK/-XH=  file. OBJ 

Description 

The  /-XH  switch  informs  TKB  that  the  task  is  not  to  have  an 
j     external  header. 

Effect 

In  an  RSX-llM-PLUS  system,  the  effect  of  the  /XH  switch  is 
I  two-fold:    the   header   space  in  the  task  image  is  not  destroyed 

:  when  the  task  is  checkpointed;  and  Executive  pool  space  is 
t,  conserved.  A  task  built  with  the  /XH  switch  does  not  have  a 
;     header  in  Executive  pool,  but  has  a  copy  of  its  header,  which  the 

Executive  uses,  in  space  allocated  physically  contiguous  to  and 
,'  below  the  task  image.  When  the  task  is  checkpointed,  the  system 
i:     writes   the   entire  task  image  and  the  header  copy  below  the  task 

into  a  checkpoint  file.   The  header  in  the   task   image   is   left 

unchanged . 

i'     Note  that  if  the  task  is  also  built   with   the   /FP  switch,   the 
floating-point  save  area  is  not  included  in  the  task  image  but  is 
'      in  the  header  copy  found  below  the  task  image. 

Interaction  with  the  INSTALL  command: 

■'  On  RSX-llM-PLUS,  the  INSTALL  switch  /XHR  interacts  with  the  TKB 
0     switch   /XH.   If  you  use  /-XH,  the  task  will  have  a  pool-resident 

header  always  unless  you  rebuild  the  task  to  have  an  external 
;     header.    If   you  use  /XH,  the  task  will  have  an  external  header, 

but  the  INSTALL  switch  /XHR  can  override  this.  The  default  use 
':  of   /XH  by  TKB  is  /XH  (external  header)  unless  this  is  changed  by 

the  INSTALL  command . 

Default 
^,  _  /XH  for  RSX-llM-PLUS;   overridden  by  /XHR  on  INSTALL   .,.,,,.  ,•>,, 
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10.1.38   /XT[:n]  —  Exit  on  Diagnostic 
File 

Task  image 
Syntax 

f ile.TSK/XT:4=f ile.OBJ 

Description 

This  switch  specifies  the  number  of  acceptable  errors.   More  than 
n  errors  are  not  acceptable. 

Effect 

TKB  exits  after  encountering  n  errors.   The  number  of  errors   can 
be  specified  as  a  decimal  or  octal  number,  using  the  convention: 

n.         indicates  a  decimal  number  (the  decimal   point   must 
be  included) . 

#n  or  n    indicates  an  octal  number. 

If  you  do  not  specify  n,  TKB  assumes  that  n  is  1. 

Default 

/-XT 
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11.1   OPTIONS 

Task   Builder   options   provide   you   with   the  means 
information  about  the  characteristics  of  your  task. 

These  options,  which  are  listed  in  Table  11-1,  can  be 
seven  Categories.  The  identifying  abbreviation 
description  of  each  category  are  listed  below: 


to   give 


divided 
and   a 


TKB 


into 
brief 


•   contr 


•   ident 


•   alloc 


•   share 


•   device 


You  use  control  options  to  affect  TKB  execution. 
ABORT  is  the  only  member  of  this  category.  You  cen 
direct  the  Task  Builder  to  abort  the  task  build 
with  this  option. 

You  use  identification  options  to  identify  your 
task's  characteristics.  You  can  specify  the  name 
of  your  task,  its  priority,  user  identification 
code,  and  partition  with  options  in  this  category. 

You  use  allocation  options  to  modify  your  task's 
memory  allocation.  With  the  options  in  this 
category,  you  can  change  the  size  of  your  task's 
stack  and  program  sections.  When  you  write 
programs  in  a  high-level  language,  you  can  change 
the  size  of  your  work  areas  and  buffers  and  declare 
the  virtual  base  address  and  size  of  program 
sections.  Finally,  you  can  declare  the  number  of 
additional  window  blocks  (if  any)  that  your  task 
requires  . 

You  use  storage-sharing  options  to  indicate  to  TKB 
that  your  task  intends  to  access  a  shared  region. 


You  use  device-specifying  options  to 
number  of  units  required  by  your 
assignment  of  logical  unit  numbers 
devices . 


specify   the 

task,  and  the 

to   physical 


alter 


synch 


You  use  the  content-altering  options  to  define  a 
global  symbol  and  value,  or  to  introduce  patches  in 
your  task  image. 


You   use   synchronous   trap 
synchronous  trap  vectors. 


options   to   define 


Some  TKB  options  are  of  interest  to  all  users  of  the  system;  others 
are  of  interest  only  to  high-level  language  programmers;  and  still 
others  are  of  interest  only  to  MACRO-11  programmers.  Table  11-1  lists 
all  the  options  alphabetically,  and  gives  a  brief  description  of  each. 
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Table  11-1 
Task  Builder  Options 


Meaning 


Interest^ 


Category 


ABOKT      Directs  TKB  to  terminate  a  task  build 

ABSPAT      Declares  absolute  patch  values 
for  conventional  tasks  or 
I-space  in  I-and  D-space  tasks 

ACTFIL     Declares  number  of  files  open 
simultaneously 

ASG         Declares  device  assignment  to 
logical  units 

CLRTR      Declares  a  group  of  shared  regions 

accessed  by  the  task  and  residing  in 

the  same  virtual  address  space  in 
the  task 

CMPRT''     Declares  completion  routine  for 
supervisor-mode  library 

COMMON     Declare  task's  intention  to  access 
LIBR       a  memory-resident  shared  region 

DSPPAT     Declares  absolute  patch  values  for 
conventional  tasks  or  D-space  in 
I-and  D-space  tasks 

EXTSCT      Declares  extension  of  a  program 
section 

EXTTSK     Declares  extension  of  the  amount  of 
memory  owned  by  a  task 

FMTBUF     Declares  extension  of  buffer  used 
for  processing  format  strings 
at  run  time 

GBLDEF      Declares  a  global  symbol  definition 

GBLINC      Includes  symbols  in  the  .STB  file 

GBLPAT      Declares  a  series  of  patch  values 
relative  to  a  global  symbol 

GBLREF      Declares  a  global  symbol  reference 


H,M 
M 

H 

H,M 
H,M 

H,M 
M 

H,M 
H,M 
H 

M 
M 
M 

H,M 
(continued  on 


contr 
alter 

alloc 

device 

share 

ident 

share 
alter 

alloc 
alloc 
alloc 

alter 
alter 
alter 

alter 
next  page) 


1.  The  user  interest  range  is  indicated  as  follows: 

•  H  indicates  options  cf  interest  to  high-level   language   (such 
as  FORTRAN)  programmers. 

•  M  indicates  options  of  interest  to  MACRO-11  programmers. 

2.  These  options  are  applicable  to  RSX-llM-PLUS  systems  only. 
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Table  11-1  (Cont.) 
Task  Builder  Options 


Option 


Meaning 


Interest 


Category 


C  -/.CL'^    Declares  global  symbol^s  to  be  H,M 

excluded  from  the  .STB  file 

LIBR       Declares  task's  intention  to  access        H,M 
a  memory-resident  shared  region 

MAXBUF     Declares  an  extension  to  the  FORTRAN       H 
record  buffer 

ODTV       Declares  the  address  and  size  of  M 

the  debugging  aid  SST  vector 

PAR        Declares  partition  name  and  H,M 

dimensions 

PRI         Declares  priority  H,M 

RESCCi'i      Declare  task's  intention  to  access  H,M 

RESLIB      a  memory-resident  shared  region 

RESSJl---    Declares  task's  intention  to  access  a      H,M 
resident  supervisor-mode  library 

R0PAr2      Declares  partition  in  which  read-only      H,M 
portion  of  multiuser  task  is  to  reside 

STACK       Declares  the  size  of  the  stack  H,M 

SUPLIB^     Declares  task's  intention  to  access  a      H,M 
system-owned  supervisor-rdode  library 

TASK        Declares  the  name  of  the  task  H,M 

TSKV       Declares  the  address  of  the  task  M 

SST  vector 

UIC         Declares  the  user  identification  code       H,M 
under  which  the  task  runs 

UNITS       Declares  the  maximum  nur.,ber  of  units        H,M 

VSECT       Declares  the  virtual  base  address  and       H,M 
size  of  a  program  section 

WNDWS       Declares  the  number  of  additional  H,M 

address  windows  required  by  the  task. 


alter 

share 

alloc 

synch 

ident 

ident 
share 

share 

ident 

al  loc 
share 

ident 
synch 

ident 

device 

a  1  loc 

al  loc 


1.  The  user  interest  range  is  indicated  as  follows: 

•  H  indicates  options  of  interest  to  high-level   language   (such 
as  FORTRAN)  programmers. 

•  M  indicates  options  of  interest  to  MACRO-11  programmers. 

2.  These  options  are  applicable  to  RSX-llM-PLUS  systems  only. 
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11.1.1   ABORT  —  Abort  the  Task-Build 

You  use  the  ABORT  option  when  you  discover  that  an   earlier   error   in 
the  terminal  sequence  causes  TKB  to  produce  an  unusable  task  image. 

The  Task  Builder,  on  recognizing  the  keyword   ABORT,   stops   accepting 
input  and  restarts  for  another  task  build. 

Syntax 

ABORT=n 


n 


An  integer  value.   The  integer  is  required  to  satisfy  the  general 
form  of  an  option;   however,  the  value  is  ignored  in  this  case. 


Default 

None 


NOTE 

If  you  type  a  CTRL/Z  at  any  time,  it 
causes  TKB  to  stop  accepting  input  and 
begin  building  the  task. 

The  ABORT  option  is  the  only  correct  way 
for  you  to  restart  TKB  if  you  discover 
an  arror  and  decide  you  do  not  want  the 
Task  Builder  output. 
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11.1.2   ABSPAT  —  Absolute  Patch 

You  use  the  ABSPAT  option  to  declare  a  series  of  object-level  patches 
starting  at  a  specified  base  address.  You  may  use  this  option  for 
conventional  or  I-and  D-space  tasks.  If  used  for  an  I-and  D-space 
task,  this  option  patches  I-space.  See  the  DSPPAT  option.  You  can 
specify  up  to  eight  fatch  values. 

Syntax 

ABSPAT=seg-name: address :vall:val2...:val8 
seg-name 

The  1-  to  6-character  Radix-50  name  of  the  segment. 

address 

Ihe  octal  address  of  the  first  patch.  The  address  can  be  on  a 
byte  boundary:  however,  two  bytes  are  always  modified  for  each 
patch:   the  addressed  byte  and  the  following  byte. 


vail 


va  '  2 


An  octal  number  in  the  range  of  0  through  177777  to  be  stored   at 
■"ddress . 


An  octal  number  in  the  range  of  0  through  177777  to  be  stored   at 
address+2 


val8 


An  octal  number  in  the  range  of  0  through  177777  to  be  stored   at 
address+16 . 


NOTE 

All  patches  must  be  within  the  segment 
address  limits  or  TKB  generates  the 
following  error  message: 


TKB--*DIAG*--Load  addtcs?  out  of  range  in  module  name 
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11.1.3   ACTFIL  --  Number  of  Active  Piles 

You  use  the  ACTFIL  option  to  declare  the  number  of  files  that  your 
task  can  have  open  simultaneously.  For  each  active  file  that  you 
specify,  TKB  allocates  approximately  512  bytes. 

If  you  specify  less  than  four  active  files  (the  default),   the   ACTFIL 

option   saves   space.    If   you   want  your  task  to  have  more  than  four 

active  files,  you  must  use  the  ACTFIL  option  to  make  the  additional 
allocation. 

You  must  include  a  language  Object  Time  System  (OTS) ,  such  as  FORTRAN, 
and  record  I/O  service  routines  (FCS  or  RMS-11)  in  your  task  image  for 
the  extension  to  take  olace.  The  program  section  that  is  extended  has 
the  reserved  name  $$FSR1. 

Syntax 

ACTFIL=file-max 

file-max 

A  decimal  integer  indicating  the  maximum  number  of  files  that  can 
be  open  at  the  same  time. 

Default 

ACTFIL=4 
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11.1.4   ASG  —  Device  Assignment 

The  ASG  option  declares  the  physical  device  that  is  assigned  to  one  or 
more  logical  units. 

Syntax 

ASG=de vice -name :unit-numl:unit-num2. . . :unit-num8 

device-name 

A  2-character  alphabetic  device  name  followed  by  a  1-  or   2-digit 

octal   unit   number.    If   your   task   uses  more  than  six  logical 

units,  you  must  use  the  UNITS  option  to   specify  the  number   of 
logical  units  that  your  task  will  use. 

unit-numl 
unit-num2 


unit-num8 

Octal  integers  indicating  the  logical  unit  numbers 
Default 

ASG=SY0:1:2:3:4,TI0:5,CL0:6 
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11.1.5   CLSTR  —  System-Owned  Cluster  of  Resident  Libraries  or  Conunons 

The  CLSTR  option  allows  you  to  link  your  program  to  one  to  six  shared 
regions,  such  as  FMS,  RMS,  FORTRAN  or  BASIC+2,  with  a  minimum  of  lost 
virtual  address  space  for  your  task.  CLSTR  allows  two  to  six  shared 
regions  in  an  RSX-llM  system  or  an  RSX-llM-PLUS  system  to  reside  in 
the  same  virtual  address  space  in  your  task. 

You  use  CLSTR  to  declare  a  cluster  or  group  of  system-owned,  resident 
libraries  or  commons  that  your  task  intends  to  access  and  have  reside 
at  the  same  virtual  address  in  the  address  sp?ce  of  your  task. 

The  term  "system-owned"  means  that  TKB  expects  to  find  the  commons  or 
libraries  named  in  the  option  and  the  symbol  table  associated  with 
them  under  UFD  [1,1]  on  device  LB:. 

Syntax 

CLSTR=library_l ,  libra ry_2  ,  .  ,,  .  library_n  :swi  tch  :apr 

library_n 

The  library  names  must  be  1-  to  6-  character  Radix-50  names.  TKB 
expects  to  find  a  symbol  definition  file  of  the  same  name  for 
each  specified  shared  region  under  UFD  [1,1]  on  device  LB:.  The 
first  specification  denotes  the  first  or  the  default  library, 
which  is  the  library  to  which  the  task  is  mapped  when  the  task 
starts  up  and  remaps  after  any  call  to  another  library. 

In  an  RSX-llM  or  RSX-llM-PLUS  system,  the  total  number  of 
libraries  to  which  a  task  may  map  is  seven.  The  number  of  the 
component  libraries  in  clusters  is  limited  to  a  maximum  of  six. 
A  cluster  must  contain  a  minimum  of  two  libraries.  It  is 
possible  to  have  two  clusters  of  three  libraries  each  or  three 
clusters  of  two  libraries  each;  any  combination  of  number  of 
clusters  and  libraries  must  equal  at  least  two  or  a  maximum  of 
six.  If  six  libraries  are  used  in  clusters,  the  task  may  map  to 
only  one  other,  separate  library. 

:switch 

The  switch  :RW  (read/write)  or  : RO  (read-only)  indicates  the  type 
of  access  the  task  requires.  All  shared  regions  in  the  cluster 
have  the  same  type  of  access . 


:apr 


The  apr  is  an  integer  in  the  range  of  1  through  7  that  specifies 
the  first  Active  Page  Register  (APR)  that  you  want  TKB  to  reserve 
for  the  cluster  of  shared  regions.  You  can  specify  it  for  a 
cluster  made  up  of  only  position-independent  shared  regions.  If 
you  omit  the  APR  par^Tieter  and  all  shared  regions  are  position 
independent,  TKB  selects  the  highest  available  APR  to  map  the 
cluster.  A  cluster  can  be  made  up  of  both  position-independent 
and  absolute  shared  regions.  If  one  absolute  shared  region  is 
present  with  position-independent  shared  regions,  the 
position-independent  shared  regions  assume  the  same  base  address 
as  that  of  the  absolute  shared  region.  However,  if  you  specify 
more  than  one  absolute  shared  region,  all  must  be  built  with  the 
same  base  address. 
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CLSTR  (Cont.) 


Default 

None 


NOTE 

All  but  the  first  shared  region  in  a 
cluster  must  be  memory-resident  overlaid 
libraries.  The  £irst  shared  region 
specified  in  the  cluster  option  can  be  a 
single-segment  structure  (nonover laid) 
or  an  overlaid  library. 
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CMPRT 


11.1.6  CMPRT  —  Completion  Routine  —  RSX-llM-PLOS  Only 

The  CMPRT  option  is  available  on  RSX-llM-PLUS  systems  only.  You  use 
this  option  to  identify  a  shared  region  as  a  supervisor-mode  library. 
The  CMPRT  option  requires  an  argument  that  specifies  the  entry  point 
of  the  completion  routine  in  the  library.  The  completion  routine 
switches  the  processor  from  supervisor  to  user  mode  and  returns 
program  control  to  the  user  task  after  the  supervisor-mode  library 
subroutine  that  was  called  from  the  user  task  has  executed. 

Two  completion  routines  are  available  in  SYSLIB: 

•  SCMPCS  restores  only  the  carry  bit  in  the  user-mode  PS. 

•  $CMPAL  restores  all  the  condition  code  bits  in   the   user-mode 
PS. 

These  routines  perform  all  the  necessary  overhead  to  switch  the 
processor  from  supervisor  to  user  mode  and  return  program  control  to 
the  user  task  at  the  instruction  following  the  call  to  a 
supervisor-mode  library  subroutine. 

Although  you  can  write  your  own  completion  routines,  it  is  best  to  use 
either  $CMPCS  or  $CMPAL  whenever  possible.  Chapter  8  discusses 
completion  routines  in  detail. 

Syntax 

CMPRT=name 


name 


A  1-  to  6-character   Radix-50   name   identifying   the   completion 
routine. 


Defe jlt 

None 
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COMMON  or  LIBR 


11.1.7   COMMON  or  LIBR  --  System-Owned  Resident  Conunon  or  System-Owned 
Resident  Library 

The  COMMON  and  LIBR  options  ate  functionally  identical;  they  both 
declare  that  your  task  intends  to  access  a  system-owned  shared  region. 
However,  by  convention,  the  COMMON  option  identifies  a  shared  region 
that  contain'"  only  data,  and  the  LIBR  option  identifies  a  shared 
region  that  contains  onlv  code. 

If  you  use  the  COMMON  option  with  an  I-  and  D-space  task,  the  common 
is  mapped  with  D-space  APRs  only  and  therefore  must  contain  data  only. 


If  you  use  the  LIBR  option  with  an 
overmapped  with  both  I-space  and  D- 


I-  and  U-space  t<:sk, 
space  APRS. 


the  library  is 


The  term  "system-owned"  means  that  TKB  expects  to  find  the  common  or 
library  named  in  the  keyword  and  the  symbol  definition  file  associated 
with  it  under  UFD  [1,1]  on  device  LE :  . 

Syntax 

COMMON  =  ;iame  :  access-code  [  :aprl 

or 
LIBR  =  name:ac cess-- cod e[  :apr] 
name 


The  1-  to  6-character  Radix-50 
library.   TKB  expects  to  find  a 
same  name  as  that  of  the  common 
.STB  under  [1,1]  of  device  LB:. 


name  specifying  the  common  or 
symbol  definition  file  having  the 
or  library  with  an   extension   of 


access-code 


The  code  RW  (read/write)  or  the  code 
the  type  of  access  the  task  requires, 


hO   (read-only)   indicating 


NOTE 

A  privileged,  task  can  change  data  in  or  move  data  to  a 
resident  common  even  though  the  task  has  been  linked  to 
the  common  with  read-only  access. 
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COMMON  or  LIBR  (Cont.) 


apr 


An  integer  in  the  range  of  1  through  7  that  specifies  the  first 
Active  Page  Register  (APR)  that  you  want  TKB  to  reserve  for  the 
shared  region.  TKB  recognizes  the  APR  only  for  a  mapped  system; 
you  can  specify  it  only  for  position-independent  shared  regions. 
If  you  omit  the  APR  parameter  and  the  shared  region  is  position 
independent,  TKB  selects  the  highest  available  APR  to  map  the 
region . 

When  a  shared  region  is  absolute,  the  base  address  of  the 
region  —  and  therefore  the  APR  that  maps  it  —  is  determined  by 
the  arguments  in  the  PAR  option  when  the  region  is  built.  Refer 
to  PAR  in  Section  11.1.18. 


Default 

None 


• 
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DSPPAT 


11.1.8   DSPPAT  --  Absolute  Patch  for  D-space 

You  use  the  DSPPAT  option  to  declare  a  series  of  object-level  patchps 
starting  at  the  specified  base  address.  This  option  is  for  making 
patches  to  the  D-space  of  an  I-  and  D-space  task.  You  may  also  use 
this  option  to  patch  a  conventional  task  at  any  location.  You  can 
specify  up  to  eight  patch  values. 

Syntax 

DSPPAT=seq-name: address :vall:val2: . . . :val8 
segname 

The  1-  to  6-character  Radix-50  name  of  the  segment. 

address 

The  octal  address  of  the  first  pat'^h.  The  address  can  be  on  a 
byte  boundary;  however,  cwo  byLes  are  always  modified  for  each 
patch:   the  addressed  byte  and  the  following  byte. 


vail 


val2 


An  octal  number  in  the  range  of  0  through  177777  to  be  stored   at 
address . 


An  octal  number  in  the  range  of  0  through  177777  to  be  stored   at 
address+2. 


val8 


an  octal  number  in  the  range  Of  0  through  177777  to  be  stored   at 
address+16 . 


NOTE 

All  patches  must  be  within  the  segment  address  limits   or 
TKB  generates  the  following  error  message: 


TKB--*DIAG*--Load  address  out  of  range  in  module-name 
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EXTSCT 

11.1.9   EXTSCT  —  Prog-am  Section  Extension 

You  use  the  EXTSCT  option  to  extend  a  program  section. 

If  the  program  section  to  be  extended  has  the  attribute  CON 
(concatenated) ,  TKB  extends  the  section  by  the  number  of  bytes  you 
specify  in  the  EXTSCT  option.  If  the  program  section  has  the 
attribute  OVR  (overlay),  TKB  extends  the  section  only  if  the  length 
you  specify  in  the  EXTSCT  option  is  greater  than  the  length  of  the 
program  section. 

Syntax 

EXTSCT=p-sect-name:extension 
p-aect-name 

A  1-  to  6-character  radix-50  name  specifying  the  program  section 
to  be  extended. 

extension 

An  octal  integer  that  specifies  the  number  of  bytes  by  which  to 
extend  the  program  section. 

Example 

In  the  following  example,  the  program  section  BUFF  is  200  bytes 
long. 

EXTSCT=BUFF:250 

The  number  of  bytes  by  which  TKB  extends  the  program  section  BUFF 
depends  on  the  CON/OVR  attribute: 

•  For  CON,  the  extension  is  250  bytes. 

•  For  OVR,  the  extension  is  50  bytes. 

TKB  extends  the  program  section  if  it  encounters  the  program 
section  name  in  an  input  object  file  or  in  the  overlay 
description  file. 

Default 

None 
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EXTTSK 


11.1.10   EXTTSK  —  Extend  Task  Memory 

The  EXTTSK  option  directs  the  system  to  allocate  additional  memory  for 
your  task  when  it  is  installed  in  a  system-controlled  partition. 

The  amount  of  memory  that  the  system  allocates  for  your  task  is  the 
sum  of  the  task  siz-i  plus  the  increment  you  specify  (rounded  up  to  the 
nearest  32-word  boundary).  If  the  task  is  built  for  a  user-controlled 
partition,  the  allocation  of  task  memory  reverts  to  the  partition 
size. 

This  option  extends  only  the  D-  space  of  an  I-  and  D-space  task. 

In  an  unmapped  system,  TKB  ignores  the  EXTTSK  keyword. 


NOTES 


You  should  not  use  the  EXTTSK  option 
to  extend  a  task  containing 
memory-resident  overlays  because  the 
system  does  not  map  the  extended 
area. 

When  you  use  the  EXTTSK  option  to 
extend  a  checkpointable  task  that 
has  been  declared  checkpointable 
with  the  /AL  switch,  the  check  point 
file  within  the  task  image  is  the 
size  of  the  task  plus  the  size  of 
the  extended  task  area. 


Be  careful  when  extend 
D-space  task  that  i 
library  which  contains 
instructions.  Normal 
are  mapped  in  both 
D-space  allowing 
instructions  to  be  int 
extension  length  mus 
into  the  area  mapped  f 
or  the  library  will 
I-space  only. 


ing  an  I-  and 
s   linked  to  a 

both  data  and 
ly,   libraries 

I-space   and 

data    and 

ermixed.    The 

t   not   extend 

ox.    the  library 

be  mapped  in 


Syntax 

EXTTSK=length 

length 

A  decimal   number    in   the   range   0<n<65,535.    specifying   the 
increase  in  task  memory  allocation  (in  words). 

Default 

The  task  is  extended  to  the  size  specified  in  the  PAR  option  (see 
Section  11. 1. 18)  . 
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FMTBUF 


11.1.11   FMTBUF  --  Format  Buffer  Size 

The  FMTBUF  option  declares  the  length  of  the  internal  working  storage 
that  you  want  TKB  to  allocatr  within  your  task  for  compiling  format 
specifications  at  run  time.  The  length  of  this  area  must  equal  or 
exceed  the  number  of  bytes  in  the  longest  format  string  to  be 
processed . 

Run-time  compilation  jrs  whenever  an  array  is  referred  to  as  the 
source  of  formatting  information  within  a  FORTRAN  I/O  statement.  The 
program  section  that  TKB  extends  has  the  reserved  name  $S0BF1. 

Syntax 

FMTBUF=max- format 
max-forroat 

A  decimal  integer,  larger  than  the  default,   that   specifies   the 
number  of  characters  in  the  longest  format  specification. 

Default 

FMTBUF=132 
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GBLDEF 


11.1.12   GBLDEF  —  Global  Symbol  Definition 

You  use  the  GBLDEF  option   to   declare   the   definition   of   a   global 
symbol . 

TKB  considers  th^s  symbol  definition  to  be  absolute.   It  overrides  any 
definition  in  your  input  object  modules. 

Syntax 

GBLDEF = symbol -name : symbol -value 
symbol-name 

A  1-  to  6-character  Radix-50  name  of  the  defined  symbol. 

symbol-value 

An  octal  number  in  the  range  of  0  through  177777  assigned  to   the 
def  i  ned  symbol . 

Default 

None 
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GBLINC 


11.1.13   GBLINC  --  Include  Global  Symbols 

The  GBLINC  option  directs  the  Task  Builder  to  include  the  symbol  or 
symbols  specified  in  this  option  in  the  .STB  file  being  generated  by 
the  link  operation  in  which  this  option  ippears.  This  option  is 
intended  for  use  when  creating  shared  regions,  in  particular  shared 
libraries,  when  you  want  to  force  particular  modulej  to  be  linked  to 
your  task  that  references  this  library.  The  global  symbol  references 
specified  by  this  option  must  be  satisfied  by  some  module  or  GBLDEF 
specification  when  you  build  the  task. 

Syntax 

GBLINC  =  symbol-name, symbol-name , ....  , symbol-name 
symbol-name 

The  symbol  to  be  included. 
Default 

None 


• 
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• 


m 


GBLPAT 


11.1.14   GBLPAT  ~  Global  Relative  Patch 

The  GBLPAT  option  declares  a  series  of  object-level  patch  values 
starting  at  an  offset  relative  to  a  global  symbol.  You  can  specify  up 
to  eight  patch  values. 

Syntax 

GBLPAT=seg-name  :sym-name [+/-of f set]  :vall:val2...:val8 
seg-name 

The  1-  to  6-character  Radix-50  name  of  the  segment. 
sym-name 

A  1-  to  6-character  Radix-50  name  specifying  the  global  symbol. 
offset 

An  octal  number  specifying  the  offset  from  the  global  symbol. 
vail 

An  octal  number  in  the  range  of  0  through  177777  to  be  stored   at 
the  octal  address  of  the  first  patch. 


val2 


An  octal  number  in  the  range  of  0  through  177777  to  be  stored   at 
the  first  address+2. 


val8 


An  octal  number  in  the  range  of  0  through  177777  to  be  stored   at 
the  first  address+14. 


Default 

None 


NOTE 

All  patches  must  be  within  the  segment 
address  limits  or  TKB  generates  a  fatal 
error , 
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GBLREF 


11.1.15   GBLREF  —  Global  Symbol  Reference 

The  GL-LREF  option  declares  a  global  symbol  reference.  The  reference 
originates  in  the  root  segment  of  the  task.  This  keyword  is  used  for 
memory-resident  overlays  of  shared  regions. 

Syntax 

GBLREF=symbol-name, symbol-name . . . , symbol-name 
symbol-name 

A  1-  to  6-character  name  of  a  global  symbol  reference. 
Default 

None 
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GBLXCL 


11.1.16   GBLXCL  —  Exclude  Global  Symbols 

The  GBLXCL  option  keyword  directs  TKB  to  exclude  from  the  symbol 
definition  file  of  a  shared  region  the  symbol (s)  specified  in  the 
option . 

Syntax 

GBLXCL=symbol-name , symbol-name. . . , symbol-name 
symbol-name 

The  symbol (s)  to  be  excluded. 
Default 

None 


11-21 


OPTIONS 


LIBR 

11.1.17      LIBR  —   System-Owned    Library 
Refer    to  COMMON    in   Section    11.1.7. 
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MAXBUF 


11.1.18   MAXBUF  —  Maximum  Record  Buffer  Size 

The  MAXBUF  option  declares  the  maximum  record  buffer  size  required  for 
any  file  used  by  the  task. 

If  your  task  requires  a  maximum  record  size  that  exceeds  the  default 
buffer  length,  you  must  use  this  option  to  extend  the  buffer. 

You  must  also  include  a  language  Object  Time  System  (OTS) ,  such  as 
FORTRAN,  in  your  task  image  for  the  extension  to  take  place.  The 
program  section  that  is  extended  has  the  reserved  name  $$1081. 

Syntax 

MAXBUF=max- record 

max-record 

A  decimal  integer,  larger  than  the  default,   that   specifies   the 
maximum  record  size  in  bytes. 

Default 

MAXBUF=133   • 
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ODTV 


11.1.19   ODTV  --  ODT  SST  Vector 

The  ODTV  option  declares  that  a  global  symbol  is  the  address  of  the 
ODT  Synchronous  System  Trap  vector.  You  must  define  the  global  symbol 
in  the  main  root  segment  of  your  task. 

Syntax 

ODTV" symbol -name :vector-length 
symbol-name 

A  1-  to  e-character  Radix-50  name  of  a  global  symbol. 

vector-length 

A  decimal  integer  in  the  range  of  1   through   32   specifying   the 
length  of  the  SST  vector  in  words. 

Default 

None 
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PAR 


11.1.20   PAR  --  Partition 

The  PAR  option  identifies  the  partition  for  which  your  task  is  built. 

In  a  map^ied  system,  you  can  install  your  task  in  any  system  partition 
or  user  partition  large  enough  to  contain  it.  In  an  unmapped  system, 
your  task  is  bound  to  physical  memory.  Therefore,  you  must  install 
your  task  in  a  partition  starting  at  the  same  memory  address  as  that 
of  the  partition  for  which  it  was  built. 

Syntax 

PAR=pname[ :base: length] 
pname 

The  name  of  the  partition. 

base 

The  octal  byte  address  defining  the  start  of  the  partition.  On 
an  unmapped  system,  the  physical  address  must  be  specified.  On  a 
mapped  system,  the  base  must  be  0  for  a  task  or  a  4K  boundary  for 
a  shared  region. 

length 

The  octal  number  of  bytes  contained  in  the  partition. 

In  a  mapped  system,  a  length  of  0  implies  a  system-controlled 
par t  i  t  ion  . 

If  the  target  sy- '-.em  is  mapped  and  you  specify  a  parti  ion  length 
that  is  greater  than  the  length  of  your  task,  the  Ta-sk  Builder 
automatically  extends  the  length  of  your  task  to  match  ♦■'le  length 
of  the  partition.  This  procedure  is  equivalent  to  using  the 
EXTTSK  keyword  to  increase  the  task  memory.  If  your  cask  size  is 
greater  than  the  partition  size  that  you  specify,  TKB  generates 
the  following  error  message: 

TKB--*DIAG*-Task  has  illegal  memory  limits 

Whether  or  not  '..he  target  system  is  mapped,  the  Task  Builder  does 
not  extend  the  length  of  a  shared  region,  or  any  task  built 
without  a  header,  to  match  the  specified  partition  length. 

If  you  do  not  specify  the  base  and  length,  TKB  tries   to   obtain   that 

information   from   the  system  on  which  you  are  building  your  task.   If 

you  have  specified  a  partition  that  resides  in  that  system,  TKB  can 
obtain  the  base  and  length. 
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PAR  (Cont.) 


TKB  binds  the  task  to  the  addresses  defined  by  the  partition  base.  If 
the  partition  is  user  controlled,  TKB  verifies  that  the  task  does  not 
exceed  the  length  specification. 

On  RSX-llM-PLOS,  a  TK3  command  sequence  or  build  file  for  a 
memory-resident  overlaid  library  must  contain  the  statement  PAR=xxx, 
where  xxx  is  the  same  name  as  that  of  the  region  being  built. 

Default 

PAR=GEN 
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PRI 


11.1.21  PRI  —  Priority 

The  PRI  option  declares  your  task's  execution  priority. 

On  systems  with  multiuser  protection,  you  cannot  run  a  task  at  a 
priority  that  is  greater  than  the  system  priority  (50)  unless  it  is 
installed  or  run  from  a  privileged  terminal.  If  you  are  working  from 
a  privileged  terminal,  and  you  do  not  override  this  option  by 
specifying  a  different  priority  when  you  install  your  task,  the  system 
uses  this  priority. 

Syntax 

PRI=pr ior ity-number 
priority-number 

A  decimal  integer  in  the  range  of  1  through  250 

Default 

Established   by   Install;    refer   to   the   RSX-llM/M-PLUS   MCR 
Operations  Reference  Manual. 
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RESCOM  or  RESLIB 


11.1.22   RESCOM  or  RESLIB  —  Resident  Common  or  Resident  Library 

The  RESCOM  and  RESLIB  options  are  functionally  identical;  they  both 
declare  that  your  task  intends  to  access  a  user-owned,  shared  region. 
However,  by  convention  the  RESCOM  option  identifies  a  shared  region 
that  contains  only  data  and  the  RESLIB  option  identifies  a  shared 
region  that  contains  only  code. 

If  you  use  the  RESCOM  option  with  an  I-  and  D-space  task,  the  common 
is  mapped  with  D-space  APRs  only  and  therefore  must  contain  data  only. 

If  you  use  the  RESLIB  option  with  an  I-  and  D-space  task,  the  library 
is  overmapped  with  both  I-space  and  D-space  APRs. 

The  term  "user-owned"  means  that  the  resident  common  or  library  and 
the  symbol  definition  file  associated  with  it  can  reside  under  any  UFD 
that  you  choose.  You  can  specify  the  UFD  and  remaining  portions  of 
the  file  specification  for  both  options.  You  must  not  place  comments 
on  the  same  line  with  either  option. 

Syntax 

RESCOM=f i le-specificat ion/access-code [:apr] 


RESLIB=f i le- spec i ficat ion/access -code [  :apr] 

file-specification 

The  memory  image  file  of  the  resident  common  or  resident  library. 
The  file  specification  format  is  discussed  in  Chapter  1. 

access-code 

The  code  RW  (read/write)  or  the  code  RO   (read-only),   indicating 
the  type  of  access  required  by  the  task. 

NOTE 

A  privileged  task  can  change  data  in  or  move  data  into  a 
resident  common  even  though  the  task  has  been  linked  to 
the  common  with  read-only  access. 


apr 


An  integer  in  the  range  of  1  through  7  that  specifies  the  first 
Active  Page  Register  (APR)  that  you  want  TKB  to  reserve  for  the 
common  or  library.  TKB  recognizes  the  APR  argument  only  for  a 
mapped  system.  You  can  specify  it  only  for  position-independent 
shared  regions.  If  the  APR  parameter  is  omitted  and  the  shared 
region  is  position  independent,  TKB  selects  the  highest  available 
APR  to  map  the  region. 

When  a  shared  region  is  absolute,  the  base  address  of  the 
region  --  and  therefore  the  APR  that  maps  it  --  is  determined  by 
the  arguments  in  the  PAR  option  when  the  region  is  built.  Refer 
to  PAR  in  Section  11.1.18. 
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OPTIONS 


RESCOM  or  RESLIB  (Cont.) 


NOTES 


1.  The  Task  Builder  expects  to  find  a  symbol  definition 
file  having  the  same  name  as  that  ot  the  memory  image 
file  but  with  a  file  type  of  .STB,  on  the  same  device 
and  under  the  same  UFD  as  that  of  the  memory  image 
file. 

2.  Regardless  of  the  version  number  you  give  in  the  file 
specification,  TKB  uses  the  latest  version  of  the 
.STB  file. 


Default 


When  you  omit  portions  of  the  file-specification,   the   following 
defaults  apply: 

•  UFD  -  Taken  from  current  terminal  UIC 

•  Device  -  SYO: 

9   File  type  -  .TSK 

•  File  version  -  Latest 
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OPTIONS 


RESLIB 

11.1.23   RESLIB  —  Resident  Library 
Refer  to  RESCOM  in  Section  11.1.21. 
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OPTIONS 


RESSUP 


11.1.24   RESSUP  —  Resident  Supervisor-Mode  Library  —  RSX-IIM-PLUS  only 

The  RESSUP  option  declares  that  your  task  intends  to  access  a 
usPt-owned,  supervisor-mode  library.  The  term  "user-owned"  means  that 
the  library  and  the  symbol  definition  file  associated  with  it  can 
reside  under  any  UFD  that  you  choose.  You  can  specify  the  UFD  and 
remaining  portions  of  the  file  specification.  You  must  not  place 
comments  on  the  line  with  RESSUP. 

Syntax 

RESSUP=f ile-speci float ion/ [-]SV( :apr] 

file-specification 

The  memory  image  file  of  the  supervisor-mode  library.  The  file 
specification  has  the  standard  RSX-llM/RSX-llM-PLUS  format 
discussed  in  Chapter  1. 


/(-ISV 


«pr 


The  code  /SV  or  /-SV  to  indicate  whether  TKB  includes 
mode-switching  vectors  within  the  user  task.  If  you  specify  /SV, 
TKB  includes  a  4-word,  mode-switching  vector  within  the  address 
space  of  the  user  task  for  each  call  to  a  supervisor-mode  library 
subroutine.  If  you  specify  /-SV,  you  must  provide  your  own 
mode-switching  vector.  Providing  your  own  mode-switching  vectors 
is  useful  if  your  library  contains  threaded  codf .  It  is  best  to 
use  the  sy.  tern-supplied  vectors  whenever  poGsible. 


An  integer  in  the  range  of  0  through  7  that  specifies   the   first 
Supervisor   Active  Page  Register  that  you  want  TKB  to  reserve  for 

your  supervisor-mode  library.   You  can  specify  an   APR   only   for 

position-independent,   supervisor-mode  libraries.   The  default  is 
the  lowest  available  APR. 

The  library  at  virtual  0  must  have  the  CSM  dispatcher  present   in 

the  system-supplied  completion  routine  described  in  Chapter  8. 


NOTES 


1.  The  Task  Builder  expects  to  find  a  symbol  definition 
file  having  the  same  name  as  that  of  the  memory  image 
file  but  with  a  file  type  of  .STB,  on  the  same  device 
and  under  the  same  UFD  as  that  of  the  memory  image 
file. 

2.  Regardless  of  the  version  number  you  give  in  the  file 
specification,  TKB  uses  the  latest  version  of  the 
.STB  file. 
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OPTIONS 


RESSUP  (Cont.) 


Default 


When  you  omit  portions  of  the  file  specification,   the   following 
defaults  apply: 

•  UFD  -  Taken  from  the  current  terminal  UlC 

•  Device  -  SYO: 

•  File  type  -  .TSK 

•  File  version  -  Latest 
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OPTIONS 


ROPAR 


11.1.25  ROPAR  —  Read-only  Partition  —  RSX-llM-PLOS  Only 

You  use  this  option  to  declare  the  partition  in  which   the   read-only 
portion  of  your  multiuser  task  is  to  reside. 

Syntax 

ROPAR«parname 
par name 

The  partition  name  in  which  your  multiuser  task  is  to  reside. 

Default 

The  partition   in  which   the   read/write  portion  of   the   task 
resides. 
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OPTIONS 


STACK 


11.1.26   STACK  —  Stack  Size 

The  STACK  option  declares  the  maximum  size  of  the  stack  required  by 
your  task. 

The  stack  is  an  area  of  memory  that  the  MACRO-11  programmer  uses  for 
temporary  storage,  cubroutine  calls,  and  synchronous  trap  service 
linkage.  The  stack  is  referred  to  by  hardware  register  6  (SP,  the 
stack  pointer) . 

Syntax 

STACK=stack-size 

stack-size 

A  decimal  integer  specifying  the  number  of  words  required  for  the 
stack . 

Default 

STACK=256 
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OPTIONS 


SUPLIB 


11.1.27   SDPLIB  —  Supervisor-Hode  Library  —  RSX-llM-PLOS  Only 

This  option  declares  that  your  task  intends  to  access  a  system-owned, 
supervisor-mode  library.  The  term  "system-owned"  means  that  TKB 
expects  to  find  the  supervisor-mode  library  and  the  symbol  definition 
file  associated  with  it  in  UFD  [1,1]  on  device  LB:. 

Syntax 

SUPLIB-name: [-]SV[:apr] 


name 


The  1-  to  6-character  Radix-50  name  specifying  the  system-owned, 
supervisor-mode  library.  TKB  expects  to  find  a  symbol  definition 
file  having  the  same  name  as  that  of  the  library  with  a  file 
version  of  .STB  under  [1,1]  of  device  LB:. 


:1-1SV 


apr 


The  code  /SV  or  /-SV  to  indicate  whether  TKB  includes 
mode-switching  vectors  within  the  user  task.  If  you  specify  /SV, 
TKB  includes  a  4-word  mode-switching  vector  within  the  address 
space  of  the  user  task  for  each  call  to  a  supervisor-mode  library 
subroutine.  If  you  specify  /-SV  you  must  provide  your  own  mode- 
switching  vector.  Providing  your  own  mode-switching  vectors  is 
useful  if  your  library  contains  threaded  code.  It  is  best  to  use 
the  system-supplied  vectors  whenever  possible. 


An  integer  in  the  range  of  0  through  7  that  specifies  the  first 
Supervisor  Active  Page  Register  that  TKB  is  to  reserve  for  the 
library.  You  can  specify  an  APR  only  for  position-independent, 
supervisor-mode  libraries.  The  default  is  the  lowest  available 
APR. 

The  library  at  virtual  0  must  have  the  CSM  dispatcher  present  in 
the  system-supplied  completion  routine  described  in  Chapter  8. 


Default 

None 
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OPTIONS 


TASK 


11.1.28   TASK  —  Task  Name 

The  TASK  option  gives  your  task  an  installed  name  different   from   its 
task  image  name. 

Syntax 

TASK=task-name 
task-name 

A  1-  to  6-character  name  identifying  your  task. 
Default 

The  first  six  characters  of  the  task  image  file  name  identify  the 
task  when  the  task  is  installed. 
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OPTIONS 


TSKV 


11.1.29   TSKV  —  Task  SST  Vector 

The  TSKV  option  declares  that  a  global  symbol  is  the  address  of  the 
task  Synchronous  System  T; ap  (SST)  vector.  You  must  define  the  global 
symbol  in  the  main  root  segment  of  your  task. 

Syntax 

TSKV= symbol -name: vector -length 
symbol -name 

A  1-  to  6-jharacter  name  of  a  global  symbol  . 

vector-length 

A  decimal  integer  in  the  range  of  1   through   32   specifying   the 
length  of  the  SST  vector  in  words. 

Default 

None 
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OPTIONS 


UIC 


11.1.30  OIC  —  User  Identification  Code 

The  UIC  option  declares  the  User  Identification  Code   (UIC)   for   your 
task  when  you  run  it  with  a  time-based  schedule  request. 

Syntax 

UIC« [group, member ] 

group 

An  octal  number  in  the  range  of  1  through  377,  or  a  decimal 
number  in  the  range  of  1  through  255.  Decimal  numbers  must  be 
followed  by  a  decimal  point  (.). 


member 


An  octal  number  in  the  range  of  1  through  377,  or  a  decimal 
number  in  the  range  of  1  through  255.  Decimal  numbers  must  be 
followed  by  a  decimal  point  (.). 


• 


Default 


The  UIC  that  the  Task  Builder   is   running   under   (r;otmally   the 
terminal  UIC) . 
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OPTIONS 


UNITS 


11.1.31   UNITS  --  Logical  Unit  Usage 

The  UNITS  option  declares  the  number  of  logical  units  that   your   task 
uses. 

Syntax 

UNITS=max-units 

max-units 

A  decimal  integer  in  the  range  of  0  through  250  specifying  the 
maximum  number  of  logical  units.  A  2-word  block  is  allocated  in 
the  task's  header  for  every  logical  unit.  A  task  that  uses  many 
logical  units  can  use  a  significant  portion  of  dynamic  memory 
because  the  header  is  in  dynamic  memory  when  the  task  is 
executing.   The  /XH  switch  affects  pool  usage  by  the  task  header. 

Default 

UNITS=6 
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OPTIONS 


VSECT 


11.1.32  VSECT  ~  Virtual  Program  Section 

The  VSECT  option  specifies  the  virtual  base  address,   virtual  length, 

and,   optionally,   the   physical  memory  allocated  to  the  named  program 

section.   Refer  to  Chapter  5  for  more  information  on   virtual  program 
sections . 

Syntax 

VSECT=p-sect-name:ba3e:window[ : physical -length] 
p-sect-name 

A  1-  to  6-character  program  section  name. 


base 


An  oct^l  value  representing   the  virtual   base   address   of  the 

program  section  in  the  range  of  0  through  177777.   If  you  use  the 

mapping  directives,  the  value  you  specify  must  be  a  multiple  of 
4K. 

window 

An  octal  value  specifying  the  amount  of  virtual  address  space  in 
bytes  allocated  to  the  program  section.  Base  plus  window  must 
not  exceed  177777  (octal). 

physical- length 

An  octal  value  specifying  the  minimum  amount  of  physical  memory 
to  be  allocated  to  the  section  in  units  of  64-byte  blocks.  TKB 
rounds  this  value  up  to  the  next  256-word  limit.  This  value, 
when  added  to  the  task  image  size  and  any  previous  allocation, 
must  not  cause  the  total  to  exceed  2048K  bytes.  If  you  do  not 
specify  a  length,  TKB  assumes  a  value  of  0. 

Default 

Physical-length   defaults    to   0. 
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OPTIONS 


WNDWS 


II. 1. 3  3  WNDWS  --  Number  of  Address  Windows 

The  WNDWS  option  declares  the  number  of  address   windows   required  by 

the   task   in   addition  to  those  needed  to  map  the  task  image,  and  any 

mapped  array  or  shared  region.   The  number  specified  is  equal   to  the 
number  of  simultaneously  mapped  regions  the  task  will  use. 

Syntax 

WNDWS=n 


n 


# 


An  integer  in  the  range  1  through  7  in  an  RSX-llM   system   and   1 
through  23  In  an  RSX-llM-PLUS  system. 


Default 

WNDWS=0 
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APPENDIX  A 
TASK  BUILDER  INPUT  DATA  FORMATS 

An  object  module  is  the  fundamental  unit  of  input  to  the  Task  Builder 
(TKB) .  You  create  an  object  module  by  using  any  of  the  standard 
language  processors  (for  example,  MACRO-11  or  FORTRAN)  or  by  using  TKB 
itself  (symbol  definition  file).  The  RSX-llM/M-PLUS  librarian  (LBR) 
gives  you  the  capability  to  combine  a  numbeir  of  object  modules  into  a 
single  library  file. 

An  object  module  consists  of  variable-length  records  of  information 
that  describe  the  contents  of  the  module.  These  records  guide  TKP  in 
translating  the  object  language  into  a  task  image.  Six  record  (block) 
types  are  included  in  the  object  language: 

Declare  global  symbol  directory  (GSD)  record  (type  1) 

End  of  global  symbol  directory  (GSD)  record  (type  2) 

Text  information  (TXT)  record  (type  3) 

Relocation  directory  (RLD)  record  (type  4) 

Internal  symbol  directory  (ISD)  record  (type  5) 

End-of-module  record  (type  6) 


'"'KB  requires  at  least  five  of  these  record  types  in  each  object 
module.  The  only  record  type  that  it  does  no:  require  is  the  internal 
symbol  directory. 


The  various  record  types  ar 
as  illustrated  in  Figure 
declare-GSD  record  and  end 
declare-GSD  records  can 
before  an  end-of-GSD  record 
the  end-of-module  record, 
before  the  first  TXT  record 
appear  anywhere  in  the  fi 
the  file  between  the  initia 
record . 


e  defined  according  to  a  prescribed  format, 

A-1.    An  object  module  must  begin  with  a 

with  an  end-of-module   record.    Additional 

occur   anywhere  in  the  file,  but  must  occur 

An  end-of-GSD  record  must  appear   before 

and   at   least  one  RLD  record  must  appear 

Additional   RLD   and   TXT   records   can 

le.   The  ISD  records  can  appear  anywhere  in 

1  declare-GSD  record  and  the   end-of-module 


Object  module  records  are  variable  length  and  are  identified  by  a 
record  type  code  in  the  first  byte  of  the  record.  The  format  of 
additional  information  in  the  record  c'epends  on  the  record  type. 
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TASK  BUILDER  INPUT  DATA  FORMATS 


The  following  sections  describe   each   of   the   six   record   types 
greater  detail.   The  outline  of  these  sections  is  as  follows: 


in 


A 

1 

Declare  Globa 

A 

1 

1 

Module  Name  ( 

A 

1 

2 

Control  Secti 

A 

1 

3 

Internal  Sytnb 

A 

1 

4 

Transfer  Addr 

A 

1 

5 

Global  Symbol 

A 

1 

6 

Program  Secti 

A 

1 

7 

Program  Versi 

A 

1 

8 

Mapped  Array 

A 

1 

9 

Completion  Ro 

A 

2 

End  of  Global 

A 

3 

Text  Informat 

A 

4 

Relocation  Di 

A 

4 

1 

Internal  Relo 

A 

4 

2 

Global  Reloca 

A 

4 

3 

Internal  Disp 

A 

4 

4 

Global  Displa 

A 

4. 

5 

Global  Additi 

A 

4 

6 

Global  Additi 

A 

4 

7 

Location  Coun 

A 

4 

8 

Location  Coun 

A 

4 

9 

Program  Limit 

A 

4 

10 

Program  Secti 

A 

4 

11 

Program  Secti 

A 

4. 

12 

Program  Secti 

A 

4 

13 

Program  Secti 
Type  16) 

A 

4 

14 

Complex  Reloc 

A 

4 

15 

Resident  Libr 
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A.l   DECLARE  GLOBAL  SYMBOL  DIRECTORY  RECORD 

The  global  symbol  directory  (GSD)  record  contains  all  the  information 
required  by  TKB  to  assign  addresses  to  global  symbols  and  to  allocate 
the  virtual  address  space  required  by  a  task. 

GSD  records  are  the  only  records  processed  by  TKB  in  its  first  pass; 
therefore,  you  can  save  substantial  time  by  placing  all  GSD  records  at 
the  beginning  of  a  module  (because  the  Tas)«  Builder  has  to  read  less 
of  the  file) . 

GSD  records  contain  nine  types  of  entries: 

•  Module  name  (type  0) 

•  Control  section  name  (type  1) 

•  Internal  symbol  name  (type  2) 

•  Transfer  address  (type  3) 

•  Global  symbol  name  (type  4) 
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TASK  BUILDER  INPUT  DATA  FORMATS 

•  Program  section  name  (type  5) 

•  Program  version  identification  (type  6) 

•  Mapped  array  declaration  (type  7) 

•  Completion  routine  name  (type  10) 

TASK  BUILDER  DATA  FORMATS 


GSD 


RLD 


GSD 


TXT 


TXT 


RLD 


Initial  Declare  GSD 

Initial  Relocation  Directory 

Additional  GSD 

Text  Information 

Text  Information 

Relocation  Directory 


GSD 


END  GSD 


ISD 


ISD 


TXT 


TXT 


TXT 


END  MODULE 


Additional  GSD 
End  of  GSD 

Internal  Symbol  Directory 
Internal  Symbol  Directory 
Text  Information 
Text  Information 
Text  Information 
End  of  Module 


Figure  A-1   General  Object  Module  Format 


Each  entry  type  is  represented  by  four  words  in  the   GSD   record.    As 

shown   in   Figure   A-2,   the   first   two   words  contain   six  Radix-50 

characters,  the  third  word  contains  a  flag  byte  and   the   entry   type 

identification,   and   the   fourth  word  contains  additional  information 
about  the  entry. 
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TASK  BUILDER  INPUT  DATA  FORMATS 


A. 1.1   Module  Name  (Type  0) 

The  module  name  entry  (two  words)  declares  the  name  of  the  object 
module.  The  name  need  not  be  unique  with  respect  to  other  object 
modules  (that  is,  modules  are  identified  by  file,  not  module  name), 
but  only  one  such  declaration  can  occur  in  any  given  object  module. 
Figure  A-3  illustrates  the  module  entry  name  format. 


0 

RECORD    , 
TYPE 

RAD50 
NAME 

ENTRY  TYPE 

FLAGS 

VALUE 

RAD50 
NAME 

TYPE 

FLAGS 

VALUE 

RAD50 
NAME 

TYPE 

FLAGS 

_                   1 

■ — 1 

VALUE 

RAD50 
NAME 

TYPE 

FLAGS 

VALUE 

Figure  A-2   Global  Symbol  Directory  Record  Format 


MODULE 
NAME  (2  WORDS) 


ENTRY 
TYPE 


Figure  A-3   Module  Name  Entry  Format 


A-4 
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A.  1.2   Control  Section  Name  (Type  I) 

Control  sections,  which  include  absolute  sections  (ASECTs) ,  blank,  and 
named  control  sections  (CSECTs) ,  are  replaced  in  RSX-llM  by  program 
sections  (PSECTs).  For  compatibility  with  other  systems,  TKB 
processes  ASECTs  and  both  forms  of  CSECTs.  Section  A. 1.6  details  the 
entry  generated  for  a  .PSECT  directive. 

ASECTs  and  CSECTs  are  defined  in  terms  of  .PSECT  directives,  as 
follows : 

For  a  blank  CSE  a  program  section  is  defined  with  the  following 
attributes : 

.PSECT  ,LCL,REL,CON,RW, I,LOW 
For  a  named  CSECT,  the  program  section  is  defined  as: 

.PSECT  name,  GBL, REL ,OVR, RW, I , LOW 
For  an  ASECT,  the  program  section  iG  defined  as: 

.PSECT  .  ABS. ,GBL,ABS, I ,OVR,RW,LOW 

TKB  processes  ASECTs  and  CSECTs  as  program  sections  with  the  fixed 
attributes  defined  above.  Figure  A-4  illustrates  the  control  section 
entry  name  format. 


CONTROL  SECTION 
NAME  (2  WORDS) 


ENTRY 
TYPE 


IGNORED 


MAXIMUM  LENGTH 


Figure  A-4   Control  Section  Name  Entry  Format 


A.  1.3   Internal  Symbol  Name  (Type  2) 

The  internal  symbol  name  entry  (two  words)  declares  the  name  o,  an 
internal  symbol  (with  respect  to  the  module)  .  TKB  does,  not  support 
internal  symbol  tables;  therefore,  the  detailed  format  of  this  entry 
is  undefined.  If  TKB  encounters  an  internal  symbol  entry  while 
reading  the  GSD,  it  ignores  that  entry.  Figure  A-5  illustrates  the 
internal  symbol  name  entry  format. 


SYMBOL 
NAME  (2  WORDS) 


ENTRY 
TYPE 


UNDEFINED 


Figure  A-5   Internal  Symbol  Name  Entry  Format 
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TASK  BUILDER  INPUT  DATA  FORMATS 


A. 1.4   Transfer  Address  (Type  3) 

The  transfer  address  entry  declares  the  transfer  address  of  a  module 
relative  to  a  program  section.  The  first  two  words  of  the  entry 
define  the  name  of  thp  program  section,  and  the  fourth  word  defines 
the  relative  offset  from  the  beginning  of  that  program  section.  If  a 
transfer  address  is  not  declared  in  a  module,  then  a  transfer  address 
must  not  be  included  in  the  GSD,  or  a  transfer  address  of  000001 
relative  to  the  default  absolute  program  section  (.  ABS.)  must  be 
specified.   Figure  A-6  illustrates  the  transfer  address  entry  format. 


NOTE 

If  the  program  section  is  absolute,  the 
offset  is  the  actual  transfer  address 
(if  not  000001)  . 


SYMBOL 
NAME  (2  WORDS) 


ENTRY 
TYPE 


=  3 


OFFSET 


Figure  A-6   Transfer  Address  Entry  Format 


A. 1.5   Global  Symbol  Name  (Type  4) 

The  global  symbol  name  entry  declares  either  a  global  reference  or  a 
definition.  Definition  entries  must  appear  after  the  declaration  of 
the  program  section  in  which  the  global  symbols  are  defined  and  before 
the  declaration  of  another  program  section  (see  Section  A. 1.6). 
Global  references  can  be  used  anywhere  within  the  GSD. 

As  shown  in  Figure  A-7,  the  first  two  words  of  the  entry  define  the 
name  of  the  global  symbol.  The  flag  byte  of  the  third  word  declares 
the  attributes  of  the  symbol,  and  the  fourth  word  defines  the  value  of 
the  symbol  relative  to  the  program  section  in  which  the  symbol  is 
defined. 


SYMBOL 
NAME  (2  WORDS) 

ENTRY 
TYPE 

=    4 

FLAGS 

VALUE 

Figuie  A-7   Global  Symbol  Name  Entry  Format 


Tabl*  A-1  lists  the  bit  assignments  of  ti. 
declaration  entry. 


Clag   byte   of   the   symbol 
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Table  A-1 
Symbol  Declaration  Flag  Byte 


Bit  Assignments 


Bit  Number  and  Name 


Setting 


Weak   qualifier 


Meaning 


The  symbol  has  a  strong 
definition  and  is  resolved  in 
the  normal  manner . 

Th«  symbol  has  a  weak 
definition  or  reference.  TKB 
ignores  a  weak  reference  (bit 
3=0).  It  also  ignores  a 
weak  definition  (bit  3=1) 
unless  a  previous  reference 
has  been  made. 


Not  used. 


2     Definition  or 
reference  type 


3     Definition 


0 
1 


Normal     definition 
reference. 


or 


Library  definition.  If  tne 
symbol  is  defined  in  a 
resident  library  STB  file,  i.he 
base  address  of  the  library  is 
added  co  the  value  and  the 
symbol  is  converted  to 
absolute  (bit  5  is  reset); 
otherwise,  the  bit  is  ignored. 

Global  symbol  reference. 

Global  symbol  definition. 


Not  used 


5     Relocation 


0 
1 


Absolute  symbol  value, 
Relative  symbol  value, 


6 
7 


Not  used. 


Not  used , 


A. 1.6   Program  Section  Name  (Type  5) 

The  program  section  name  entry  declares  the  name  of  a  program  section 
and  its  maximum  length  in  the  module.  It  also  uses  the  flag  byte  to 
declare  the  attributes  of  the  program  section. 
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You  must  construct  GSD  records  such  that  once  a  program  section  name 
has  been  declared,  all  global  symbol  definitions  pertaining  to  it  must 
appear  before  another  program  section  name  is  declared.  Global 
symbols  are  declared  with  symbol  declaration  entries.  Thus,  the 
normal  format  is  a  series  of  program  section  names  each  followed  by 
optional  symbol  declarations.  Figure  A-8  illustrates  the  program 
section  name  entry  format. 


PROGRAM  SECTION 
NAME 


ENTRY 
TYPE 


FLAGS 


MAXIMUM  LENGTH 


Figure  A-8   Program  Section  Name  Entry  Format 

Table  A-2  lists  the  bit  assignments  of  the  flag  byte   of   the   program 
section  name  entry. 


Table  A-2 
Program  Section  Name  Flag  Byte  --  Bit  Assignments 


Bit  Number  and  Name    Setting 


Meaning 


Save 


0 
1 


Normal  program  section. 

The  program   section   is   forced 
into  the  root  of  the  task. 


Library  program 
section 


Normal  program  section. 


The  program  section  is 
relocatable  and  refers  to  a 
shared  region. 


Allocation 


Program  section  references  are 
to  be  concatenated  with  other 
references  to  the  same  program 
section  to  form  the  total  memory 
allocated  to  the  section. 


Program  section  references  are 
to  be  overlaid.  The  total 
memory  allocated  to  the  program 
section  is  the  largest  request 
made  by  individual  references  to 
the  same  program  section. 

(continued  on  next  page) 
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Table  A-2  (Cont.) 
Program  Section  Name  Flag  Byte  --  Bit  Assignments 


Bit  Number  and  Name    Setting 


Meaning 


Not  used;   reserved   for   future 
DIGITAL  use. 


Access 


0 
1 


The     program    section    has 
read/write  access. 

The     program    section    has 
read-only  access. 


Relocation 


Scope 


The  program  section  is  absolute 
and  requires  no  relocation. 

The  program  section  is 
relocatable  and  references  to 
the  control  section  must  have  a 
relocation  bias  added  before 
they  become  absolute. 

The  scope  of  the  program  section 
is  local.  References  to  the 
same  program  section  are 
collected  only  within  the 
segment  in  which  the  program 
section  is  defined. 


The  scope  of  the  program  section 
is     global.      TKB    collects 


references 
section 
boun-lar  ies . 
determines 
storage   is 


to  the  program 
across  segment 
The  Task  Builder 
the  segment  in  which 
allocated  for  a 
global  program  section  either  by 
the  first  module  that  defines 
the  program  section  on  a  path, 
or  by  direct  placement  of  a 
program  section  in  a  segment 
using  t:,e  ODL  .PSECT  directive. 


Type 


The   program   section    contains 
instruction  (I)  references. 


The   program   section 
data  (D)  references. 


contains 


NOTE 

The  length  of  all  absolute   sections   is 
0. 
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A. 1.7   Program  Version  Identification  (Type  6) 

The  program  version  identification  entry  declares  the  version  of  the 
module.  TKB  saves  the  version  identification  of  the  first  module  that 
defines  a  nonblank  "ersion.  It  then  includes  this  identification  on 
the  memory  allocation  map  and  writes  the  identification  in  the  label 
block  of  the  task  image  file. 

The  first  two  words  of  the  entry  contain  the  version   identification. 

The   flag  byte  and  fourth  words  are  not  used  and  contain  no  meaningful 

information.  Figure  A-9  illustrates  the  program  version 
identification  entry  format. 


SYMBOL 

NAME 

ENTRY 
TYPE      " 

6 

0 

0 

Figure  A-9   Program  Version  Identification  Entry  Format 


A.  1.8   Mapped  Array  Declaration  (Type  7) 

The  mapped  array  declaration  entry  allocates  space  within  the  mapped 
array  area  of  task  memory.  The  array  name  is  added  to  the  list  of 
task  program  section  names  and  may  be  referred  to  by  subsequent  RLD 
records.  The  length  (in  units  of  64-byte  blocks)  is  added  to  the 
task's  mapped  array  allocation.  The  total  memory  allocated  to  each 
mapped  array  is  rounded  up  to  the  nearest  512-byte  boundary.  The 
contents  of  the  flag  byte  are  reserved  and  assumed  to  be  0. 


One  additional  window  block  is  allocated  whenever  a 
declared . 


mapped   array   is 


Figure  A-10  illustrates  the  mapped  array  declaration  entry  format 


MAPPED  ARRAY 

NAME 

ENTRY 
TYPE            ' 

FLAGS 

LENGTH  (NUMBER  OF  64BYTE  BLOCKSI 

Figure  A-10   Mapped  Array  Declaration  Entry  Format 
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A. 1.9   Completion  Routine  Definition  (Type  10) 

The  completion  routine  definition  declares  the  entry  point  for  the 
completion  routine  of  a  supervisor-mode  library.  This  data  structure 
is  created  by  the  Task  Builder  and  appears  only  in  symbol  definition 
files  of  supervisor-mode  libraries. 

As  shown  in  Figure  A-11,  the  first  two  words  of  the  entry  define  the 
name  of  the  entry  point.  The  third  word  contains  the  entry  type  byte 
and  the  flag  byte.  The  flag  byte  contains  no  meaningful  information. 
The  fourth  word  contains  the  symbol  value. 


COMPLETIO 

NA 

N  ROUTINE 

ME 

ENTRY 
TYPE 

10 

0 

VALUF 

Figure  A-11  Completion  Routine  Entry  Format 


A,  2   END  OF  GLOBAL  SYMBOL  DIRECTORY  RECORD 

The  end  of  global  symbol  directory  (end-of-GSD)  record  declares  that 
no  other  GSD  records  are  contained  further  on  in  the  module.  There 
must  be  exactly  one  end-of-GSD  record  in  every  object  module.  As 
shown  in  Figure  A-12,  this  record  is  one  word  long. 


0 

RECORD 
TVPF 

Figure  A-12   End  of  Global  Symbol  Directory  Record  Format 


A.  3   TEXT  INFORMATION  RECORD 


The   text   information   (TXT)   record   contains   a   byte    string    of 
information   that   is  to  be  written  directly  into  the  tc 
The  record  consists  of  a  load  address  followed  by  the 


task  image  file, 
byte  St r  i  ng  . 


TXT  records  can  contain  words  and/or  bytes  of  information  whose  final 
contents  have  not  yet  been  determined.  This  information  •,'  11  be  bound 
by  a  relocation  directory  record  that  immediately  folU  >  the  text 
record  (see  Section  A. 4).  If  the  TXT  record  needs  n.  -.,od  i  f  icat  ion  , 
then  no  relocation  directory  record  is  needed.  Th'is,  multiple  TXT 
records  can  appear  in  sequence  before  a  relocation  directory  record. 

The  load  address  of  the  TXT  record  is  specified  as  an  offset  from  the 
current  prograrn  section  base.  At  least  one  relocation  directory 
record  must  precede  the  first  TXT  record.  This  directory  must  declare 
the  current  program  section. 
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TKB  writes  a  text  record  directly  into  the  task  image  file  and 
computes  the  value  of  the  load  address  minus  4.  This  value  is  stored 
in  anticipation  of  a  subsequent  relocation  directory  that  modifies 
words  and/or  bytes  concain-^d  in  the  TXT  record.  When  added  to  a 
relocation  directory  displacement  byte,  this  value  yields  the  address 
of  the  word  and/or  byte  to  be  modified  in  the  task  image. 

Figure  ^-13  illustrates  the  TXT  record  format. 


0 

RECORD          - 
TYPE 

LOAD  ADDRESS 

TEXT 

TEXT 

• 
• 

1 

TEXT 

TtXT 

Figure  A-13   Text  Inf  or-nat :  on  Record  Format 


A. 4   RELOCATION  DIRECTORY  RECORD 

The  relocation  directory  (SLD)  record  contains  the  information 
necessary  to  relocate  and  link  the  preceding  TXT  record.  Every  module 
must  have  at  least  one  RLD  record  that  precedes  the  first  TXT  record. 
The  first  RLD  record  does  not  modify  a  preceding  TXT  record;  rather, 
it  defines  the  current  program  section  and  location.  RLD  records 
contain  15  types  of  entries,  classified  as  relocation  or  loc^  ion 
modification  entries: 

»  Internal  relocation  (type  1) 

•  Global  relocation  (type  2) 

•  Internal  displaced  relocation  (type  3) 

•  Global  displaced  relocation  (type  4) 
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Global  additive  relocation  (type  5) 

Global  additive  displaced  relocation  (type  6) 

Location  counter  definition  (type  7) 

Location  counter  modification  (type  10) 

Program  limits  (type  11) 

Program  section  relocation  (type  12) 

Program  section  displaced  relocation  (type  14) 

Program  section  additive  relocation  (type  15) 

Program  section  additive  displaced  relocation  (type  16) 

Complex  relocation  (type  17) 

Resident  library  relocation  (type  20) 

Each  type  of  entry  is  represented  by  a  command  byte  that  specifies  the 
type  of  entry  and  the  word/byte  modification,  followed  by  a 
displacement  byte,  and  then  by  the  information  required  for  the 
particular  type  of  entry.  The  displacement  byte,  when  added  to  the 
value  calculated  from  the  load  address  of  the  preceding  TXT  record 
(see  Section  A. 3),  yields  the  virtual  address  in  the  image  that  is  to 
be  modified. 

Table  A-3  lists  the  bit  assignments  of  the  command  byte  of  each  SifcD 
entry. 


Table  A-3 

Relocation  Directory  Command  Byte  -- 

Bit  Assignments 


Bit  Number  and  Name 


Setting 


Meaning 


0-6    Entry  type 


Potentially,  128  command  types 
can  be  specified;  currently, 
15  are  implemented. 


7     Modification 


0 

1 


The  command  modifies  an  entire 
word . 

The  command  modifies  only  one 
byte.  TKB  checks  for 
truncation  errors  in  byte 
modification  commands.  If 
truncation  is  detected  (that 
is,  if  the  modification  value 
is  greater  than  255)  ,  an  error 
occurs . 


Figuice  A-14  illustrates  the  RLD  record  format, 
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0 

RECORD 
TYPE             ^ 

DISP 

CMD 

INFO 

1 

INFO 

1 

INFO 

INFO 

DISP 

CMD 

IN 

FO 

INFO 

] 

INFO 

IN 

FO 

DISP 

CMD 

IN 

FO 

IN 

FO 

\ 

1 

IN 

FO 

IN 

1 

FO 

Figure  A-14   Relocation  Directory  Record  Format 


A. 4.1   Internal  Relocation  (Type  1) 

The  internal  relocation  entry  relocates  a  direct  pointer  to  an  address 
within  a  module.  TKB  adds  the  current  program  section  base  address  to 
a  specified  constant,  and  writes  the  result  into  the  task  image  file 
at  the  calculated  address  (that  is,  a  displacement  byte  is  added  to 
the  value  calculated  from  the  load  address  of  the  preceding  text 
block) . 
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For  example: 

A:      MOV      »A,RO 
or 
.WORD     A 
Figure  A-15  illustrates  the  internal  relocation  entry  format, 


DISP 


B 


ENTRY 
TYPE 


=  1 


CONSTANT 


Figure  A-15   Internal  Relocation  Entry  Format 

A. 4. 2  Global  Relocation  (Type  2) 

The  global  relocation  entry  relocates  a  direct  pointer  to  a  global 
symbol.  TKB  obtains  the  definition  of  the  global  symbol  and  writes 
the  result  into  the  task  image  file  at  the  calculated  address. 

For  example: 

MOV       #GLOBAL,R0 
or 

.WORD     GLOBAL 
Figure  A-16  illustrates  the  global  relocation  entry  format. 


DISP 

B 

ENTRY 
TYPE 

=    2 

SYMBOL 
NAME 

ZK.459ei 

Figure  A-16   Global  Relocation  Entry  Format 


A. 4. 3   Internal  Displaced  Relocation  (Type  3) 

The  internal  displaced  relocation  entry  relocates  a  relative  reference 
to  an  absolute  address  from  within  a  relocatable  control  section.  TKB 
subtracts  the  address  plus  2  that  the  relocated  value  is  to  be  written 
into  from  the  specified  constant,  and  writes  the  result  into  the  task 
image  file  at  the  calculated  address. 

For  example: 

CLR       177550 


or 


MOV 


177550, RO 
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Figure   A-17   illustrates   the   internal   displaced   relocation  entt] 
format. 


DISP 


ENTRY 
TYPE 


CONSTANT 


Figure  A-17   Internal  Displaced  Relocation  Entry  Format 


A. 4. 4   Global  Displaced  Relocation  (Type  4) 

The  global  displaced  relocation  entry  relocates  a  relative  reference 
to  a  global  symbol.  TKB  obtains  the  definition  of  the  global  symbol; 
subtracts  the  address  plus  2  that  the  relocated  value  is  to  be  written 
into  from  the  definition  value;  and  writes  the  result  into  the  task 
image  file  at  the  calculated  address. 

For  example: 

C&R      GLOBAL 

Ot 

MOV       GLOBAL, RO 
Figure  A-18  illustrates  the  global  displaced  relocation  entry  format. 


DISP 

B 

ENTRY 
TYPE 

4 

SYMBOL 
NAME 

Figure  A-18   Global  Displaced  Relocation  Entry  Format 


A. 4. 5   Global  Additive  Relocation  (Type  5) 

The  global  additive  relocation  entry  relocates  a  direct  pointer  to  a 
global  symbol  with  an  additive  constant,  TKB  obtains  the  definition 
of  the  global  symbol;  adds  the  specified  constant  to  the  definition 
value;  and  writes  the  result  into  the  task  image  file  at  the 
calculated  address. 

For  example: 

MOV       #GLOBAL+2,R0 
or 

.WORD     GLOBAL-4 
Figure  A-19  illustrates  the  global  additive  relocation  entry  format. 
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DISP 

B 

ENTRY 
TYPE 

5 

SYMBOL 
NAME  (2  WORDS) 

CONSTANT 

Figure  A-19   Global  Additive  Relocation  Entry  Format 


A. 4. 6   Global  Additive  Displaced  Relocation  (Type  6) 

The  global  additive  displaced  relocation  entry  relocates  a  relative 
reference  to  a  global  symbol  with  an  additive  constant.  TKB  obtains 
the  definition  of  the  global  symbol;  adds  the  specified  constant  to 
the  definition  value;  subtracts  the  address  plus  2  that  the  relocated 
value  is  to  be  written  into  from  the  resultant  additive  value;  and 
writes  the  result  into  the  tack  image  file  at  the  calculated  address. 

For  example: 


CLR 


GLOBAL+2 


or 


MOV 


GLOBAL-5,R0 


Figure  A-20  illustrates  the  global  additive  displaced  relocation  entry 
format. 


DISP 

B 

ENTRY 
TYPE 

=    6 

SYMBOL 
NAMR  (2  WORDS) 

CONSTANT 

Figure  A-20   Global  Additive  Displaced  Relocation  Entry  Format 


A. 4. 7   Location  Counter  Definition  (Type  7) 

The  location  counter  definition  entry  declares  a  current  program 
section  and  location  counter  value.  TKB  stores  the  control  base  as 
the  current  control  section;  adds  the  current  control  section  base  to 
the  specified  constant;  and  stores  the  result  as  the  current  location 
counter  value. 

Figure  A-21  illustrates  the  location  counter  definition  entry  format. 
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ENTRY 
TYPE 


PROGRAM  SECTION 
NAME  (?  WORDS) 


CONSTANT 


Figure  A-21   Location  Counter  Definition  Entry  Format 


A. 4. 8   Location  Counter  Modification  (Type  10) 

The  location  counter  modification  entry  modifies  the  current  location 
counter.  TKB  adds  the  current  program  section  base  to  the  specified 
constant  and  stores  the  result  as  the  current  location  counter. 

For  example: 

.  =  .+N 

or 

•BLKB    N 

Figure   A-22   illustrates   the   location  counter   modification   entry 

format. 


FNTRY 
TYPE 


10 


CONSTANT 


Figure  A-22  Location  Counter  Modification  Entry  Format 


A. 4. 9   Program  Limits  (Type  11) 

The  program  limits  entry  is  generated  by  the  .LIMIT  assembler 
directive.  TKB  obtains  the  first  address  above  the  header  (normally 
the  beginning  of  the  stack)  and  the  highest  address  allocated  to  the 
task.  It  then  writes  these  two  addrasses  into  the  task  image  file  at 
the  calculated  address  and  at  the  calculated  address  plus  2, 
respectively. 

For  example: 

.LIMIT 

Figure  A-23  illustrates  the  program  limits  entry  format. 
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DISP 

B 

ENTRY 
TYPE 

Figure  A-23   Program  Limits  Entry  Format 


A. 4. 10   Program  Saction  Relocation  (Type  12) 

The  program  section  relocation  entry  relocates  a  direct  pointer  to  the 
beginning  address  of  another  program  section  (other  than  the  program 
section  in  which  the  reference  is  made)  within  a  module.  TKB  obtains 
the  current  base  address  of  the  specified  program  section  and  writes 
it  into  the  task  image  file  at  the  calculated  address. 

For  example: 

.PSECT  A 
B: 

• 

.PSECT  C 
MOV  #B,RO 

or 

.WORD  B 
Figure  A-24  illustrates  the  program  section  relocation  entry  format. 


DISP 


ENTR" 
TYPE 


12 


PROGRAM  SECTION 
NAME  (2  WORDS) 


Figure  A-24   Program  Section  Relocation  Entry  Format 


A. 4. 11   Program  Section  Displaced  Relocation  (Type  14) 

The  program  section  displaced  relocation  entry  relocates  a  relative 
reference  to  the  beginning  address  of  another  program  section  within  a 
module.  TKB  obtains  the  current  base  address  of  the  specified  program 
section;  subtracts  the  address  plus  2  that  the  relocated  value  is  to 
be  written  into  from  the  oase  value;  and  writes  the  result  into  the 
task  image  file  at  ^he  calculatc-d  address. 
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For  example: 


Bt 


.PSECT  A 


.PSECT  C 
MOV  B,RO 


Figure  A-25  illustrates  the  program  section  displaced  relocation  entry 
format. 


DISP 

B 

ENTRY 
TYPE 

14 

PROGRAM  SECTION 
NAME  (2  WORDS) 

Figure  A-25   Program  Section  Displaced  Relocation  Entry  Format 


A. 4. 12   Program  Section  Additive  Relocation  (Type  15) 

The  program  section  additive  relocation  entry  relocates  a  direct 
pointer  to  an  address  in  another  program  section  within  a  module.  TKB 
obtains  the  current  base  address  of  the  specified  program  section; 
adds  this  address  to  the  specified  constant;  and  writes  the  result 
into  the  task  image  file  at  the  calculated  address. 


For  example; 


B: 


PSECT  A 


C: 


.PSECT  D 
MOV  irB+10,R0 
MOV  #C,RO 

or 

.WORD  B+10 
.WORD  C 

Figure  A-26  illustrates  the  program  section  additive  relocation   entry 
format. 
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DISP 


ENTRY 
TYPE 


15 


PROGRAM  SECTION 
NAME  (2  WORDS) 


CONSTANT 


Figure  A-26   Program  Section  Additive  Relocation  Entry  Format 


A.  4. 13   Program  Section  Additive  Displaced  Relocation  (Vype  16) 

The  program  section  additive  displaced  relocation  entry  relocates  a 
relative  reference  to  an  address  in  another  program  section  within  a 
module.  TKB  obtains  the  current  base  address  of  the  specified  program 
section;  adds  this  address  to  the  specified  constant;  subtracts  the 
address  plus  2  that  the  relocated  value  is  to  be  written  into  from  the 
resultant  additive  value;  and  writes  the  result  into  the  task  image 
file  at  the  calculated  address. 


For  example! 


,  PSECT  A 


C: 


.PSECT  D 
MOV  B+10,R0 
MOV  C,RO 

Figure   A-27   illustrates 
relocation  entry  format. 


the   program   section    additive   diplaced 


DISP 


ENTRY 
TYPE 


PROGRAM  SECTION 
NAME  (2  WORDS) 


CONSTANT 


Figure  A-27   Program  Section  Additive  Displaced  Relocation 

Entry  Format 
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A.  4. 14   Complex  Relocation  (Type  17) 

The  complex  relocation  entry  resolves  a  complex  relocation  expression. 
Such  an  expres:'ion  is  one  in  which  any  of  the  MACRO-11  binary  or  unary 
operations  are  permitted  with  any  type  of  argument,  regardless  of 
whether  the  argument  is  an  unresolved  global  symbol;  is  relocatable 
to  any  program  section  base;  is  absolute;  or  is  a  complex 
relocatable  subexpression. 

The  RLD  command  word  is  followed  by  a  string  of  numerically  specified 
ope».ation  codes  and  arguments.  The  operation  codes  each  occupy  one 
byte.  The  entire  RLD  command  must  fit  in  a  single  record.  The 
following  15  operation  codes  are  defined: 

•  No  operation  --  Byte  0 

•  Addition  (+)  --  Byte  1 

•  Subtraction  (-)  —  Byte  2 

•  Multiplication  (*)  --  Byte  3 

•  Division  (/)  --  Byte  4 

•  Logical  AND  (s)  --  Byte  5 

•  Logical  inclusive  OR  (1)  --  Byte  6 

•  Negation  (-)  --  Byte  10 

•  Complement  ("C)  —  Byte  11 

•  Store  result  (command  termination)  --  Byte  12 

•  Store  fsi]*^  with  displaced  relocation  (command 
termination)   -  By^-.c  13 

•  Fetch  global  symbol  --  Byte  16  (It  is  followed  by  four  bytes 
containing  the  symbol  name  in  Radix-50  representation.) 

•  Fetch  relocatable  value  --  Byte  T?  (It  is  followed  by  one  byte 
containing  the  program  section  number,  and  two  bytes 
containing  the  offset  within  the  program  section.) 

•  Fetch  constant  --  Byte  20  (It  is  followed  by  two  bytes 
containing  the  constant.) 

•  Fetch  resident  library  base  address  --  Byte  21  (If  the  file  is 
a  resident  library  STB  file,  the  library  base  address  is 
obtained;  otherwise,  the  base  address  of  the  taslt  image  is 
fetched . ) 

The  STORE  commands  indicate  that  the  value  is  to  be  written  into  the 
task  image  file  at  the  calculated  address. 

All  operands  are  evaluated  as  16-bit  signed  quantities  using  two's 
complement  arithmetic.  The  results  are  equivalent  to  expressions  that 
the  assembler  evaluates  internally.  The  following  rules  should  be 
noted: 

1.   An  attempt  to  divide  by   0   yields   a   0   result.    The   Task 
Builder  issue?  a  nonfatal  diagnostic  error  message. 
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2.  All  results  are  truncated  from  the  left  to  fit  Into  16  bits. 
No  diagnostic  error  message  is  issued  if  the  number  is  too 
large.  If  the  result  modifies  a  byte,  TKB  checks  for 
truncation  errors  as  described  in  Section  A. 4. 

3.  All  operations  are  performed  on  relocated  (additive)  or 
absolute  16-bit  quantities.  PC  displacement  is  applied  to 
the  result  only. 


For  example! 


A: 


.PSECT   ALPHA 


.PSECT   BETA 


Bt 


MOV      #A  +  B-G1/G26,*C177120!G3>>,R1 
Figure  A-28  illustrates  the  complex  relocation  entry  format, 


DISP 

8 

ENTRY 
TYPE 

17 

COMPLEX  STRING 

12 

Figure  A-28   Complex  Relocation  Entry  Format 


A. 4, 15   Resident  Library  Relocation  (Type  20) 

The  library  relocation  entry  relocates  a  direct  pointer  to  an  address 
within  a  resident  library. 

If  the  current  file  is  a  resident  library  symbol  definition  file 
(STB),  TKB  obtains  the  base  address  of  the  library;  adds  this  address 
to  the  specified  constant;  and  writes  the  result  into  the  task  image 
file  at  the  calculated  address.  If  the  file  is  not  associated  with  a 
resident  library,  TKB  uses  the  task  base  address. 

Figure  A-29  illustrates  the  library  relocation  entry  format. 


DISP 


ENTRY 
TYPE 


20 


CONSTANT 


Figure  A-29   Resident  Library  Relocation  Entry  Format 
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A. 5   INTERNAL  SYMBOL  DIRECTORY  RECORD 

Internal  symbol  directory  (ISO)  records  have  two  purposes: 

1.  To  pass  information  to  symbolic  debuggers  via  the  .STB  fil« 

2.  To  create  autoload  vectors  dynamically  for  the  entry  points 
of  the  library 

TBK  looks  for  global  symbol  definitions  in  jhe  input  object  modules 
and  looks  for  ISD  records  if  /DA  is  specified;  otherwise  TKB  ignores 
the  ISD  records.  Some  ISD  records  require  no  relocation  and  TKB  can 
copy  them  directly  into  the  .STB  file.  Others  will  require 
modification;  after  being  -nodified,  they  can  be  written  to  the  .STB 
file.  In  addition,  TBK  may  need  to  generate  some  ISD  records  of  its 
own  in  the  .STB  file. 

Except  for  autoloadable  library  entry  points,  TBK  puts  ISD  records 
into  the  .STB  file  only  if  the  /DA  switch  is  used  in  the  TKB  command 
line.  When  TKB  outputs  the  .STB  file,  it  writes  three  major  types  of 
ISD  records: 

•  Type  1  records,  TKB  generated  ISDs.  The  form  of  these  records 
is  language  independent. 

•  Type  3  records,  written  for  any  type  2  records  in  an  input 
object  module.  TKB  does  this  after  adding  data  and  then 
changing  the  type  to  3.  Type  2  relocatable/relocated  records 
are  those  that  contain  both  language  dependent  and  independent 
sections.  Language  processors  generate  these  records  and  TKB 
modifies  them.  They  contain  information  that  can  be  used  to 
find  the  absolute  task  image  address  of  source  program 
entities  (variables,  program  statements,  etc.) 

•  Type  4  records,  written  to  the  .STB  file  without  modification. 
Type  4  records  are  literal  records  that  contain  language 
dependent  information.  Apart  from  the  first  few  bytes,  TKB 
ignores  the  rest  of  the  record. 

These  record  formats  are  described  in  the  following  sections. 


A. 5.1   Overall  Record  Format 

ISD  records  have  the  same  basic  structure  as  all  object  language 
records.  Because  of  the  variety  of  different  types,  the  skeleton 
structure  must  include  additional  fields  that  are  common  to  all  ISD 
record  types.  The  general  format  of  all  ISD  records  is  shown  in 
Figure  A-30. 
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15 

8 

7 

0 

MUST  BE  0 

RECORD  TYPE      5 

RESERVED  (0) 

ISD  RECORD  TYPE 

RECORD  TYPE  DEPENDENT 

-■KHVjB  e? 


Figure  A-30   General  Format  of  Ail  ISD  Records 


ISD  record  types  fall  into  general  categories.   The  categories  are: 

0  --  Illegal. 

1  --  TKB-generated . 

2  --  Compiler-generated  relocatable. 

3  —  Relocated  (type  2  afte»-  TKB  processing). 

4-127  --  not  defined  and  reserved  for  future  use. 

128-255  —  literal  records;    the   type   code   identifies   the 
generating  language  processor  and  the  internal  structure. 


A. 5. 2   TKB  Generated  Records  (Type  1) 

The  content  of  this  record  type  is  a  string  of  individual  items,  each 
with  its  own  format.  The  items  are  either  star t-of-segment  items, 
task  identification  items,  or  autoloadable  entry  point  items.  The  TKB 
generated  record  is  similar  to  the  structure  of  an  RLD  or  GSD  record. 
The  general  format  is  shown  in  Figure  A-j1. 


15 

8 

7                                              0 

LENGTH  (BYTES) 

ITEM  TYPE 

CONTENT  DEPENDS  ON  ITEM  TYPE 

^K  10^9  62 


Figure  A-31   General  Format  of  a  TKB  Generated  Record 


A. 5. 2. 1   Start-of-Segment   Item    Type    (1)  -  The    format 
start-of-segment  item  type  is  shown  in  Figure  A-32. 


of 


the 
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15 


8  7 


LENGTH   8 


ITEM  TYPE   1 


SEGMENT  NAME 


SEGMENT  DESCRIPTOR  ADDRESS 


Figure  A-32   Format  of  TKB  Generated  Start-of-Segment  Item  (1) 


Pi. 5. 2.2  Task  Identification  Item  Type  (2)  -  The  task  identification 
item  type  ensures  that  a  .STB  file  and  the  task  image  being  debugged 
were  generated  at  the  same  time.  Otherwise,  symbols  that  are  found 
may  not  correspond  to  the  actual  task. 

The  task  identification  item  type  exists  to  make  the  correlation 
between  the  .STB  file  and  its  related  task  possible.  The  contents  of 
this  item  type  correspond  exactly  to  the  first  ten  words  of  an  area  in 
a  task  image  file,  which  is  in  the  TKB  created  PSECT  called  S$DBTS. 


The  format 
A-33. 


of  the  task  identification  item  type   is   shown   in   Figure 


15 

8 

7 

0 

LE"GTH       22. 

ITEM  TYPE 

2 

EIGHT-WORD  TIME  STAMP' 

TWO-WORD  NUMBER^ 

1  Its  form  IS  that  which  is  returned  by  RSX   tlM/M  PLUS  dueclive 
GTIMS 

2  TKB  generates  this  number  as  an  additional  checl-  on  correspond- 
ence  Currently  always  zero 

/K  1061  e? 
Figure  A-33   Format  of  TKB  Generated  Task  Identification  Item  (2) 


A. 5. 2. 3   Autoloadahle  Library  Entry  Point  Item  Type  (3)  -  "KB   outputs 
the   autoloadable   library   entry   pc^nt   item   into   a  .STB  file  when 

resident  libraries.   The   ISD   record   contains   the 
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The  £or:.-\at  of  the  autoloadable  entry  point  item   is   shown   in   Figure 
A-34. 


15 

8 

7 

0 

LENGiH       U. 

ITEM  TYPE       3 

-• 

SYMBOL 

NAME 

0 

FLAGS  BYTE 

ENTRY  POINT  OFFSET  FROM  LIBRARY  BASE 

SEGMENT  DESCRIPTOR  OFFSET  IN  S$SGD1 

Figu'  _  A-34   Format  of  an  Autoloadable  Library  Entry  Point  Item  (3) 

A. 5. 3   Relocatable/Relocated  Records  (Type  2) 

These  records  are  the  central  part  of  TKB's  involvement  in  debugger 
communication.  Every  item  type  in  these  records  must  be  standardized, 
and  only  standard  items  can  appear.  The  general  format  of 
relocatable/relocated  records  is  the  same  as  that  shown  in  Figure 
A-30. 

A  language  processor  outputs  these  record  types  as  type  2.  When  TKB 
processes  them,  it  changes  the  type  to  type  3.  It  also  fills  in  or 
modifies  some  L'ields.  In  the  descriptions  of  following  item  types, 
fields  that  art.  filled  in  by  TKB  are  marked  with  an  asterisk  (*). 
They  should  be  left  as  zero  in  language  processor  output. 


A. 5. 3.1   Module  Name  Item  Type  (1)  -  A  module  name  item  should  be  the 

first  ISD  entry  of  each  object  module.   A  debugger  can  assume  that  all 

following  ISD  information  up  to  the  next  module  name  item  relates  to 
this  module. 

The  language  code  is  included  so  that  a  debugger  for  a  specific 
language  can  determine  whether  to  ignore  a  module  if  it  is  written  for 
another  language.  The  language  code  has  the  same  range  of  values  as 
that  of  a  language-dependent  ISD  record  (128-255)  and  has  the  same 
meaning . 

The  format  of  the  module  name  item  type  is  shown  in  Figure  A-35. 
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15                                            8 

7                                           0 

LENGTH 

ITEM  TYPE       1 

MUST  BE  0 

LANGUAGE  CODE 

MODULE  NAME' 

1  A  counted  ASCII  string  of  the  required  length  A  counted  ASCII 
siring  is  a  byte  string  in  which  the  'irsl  byte  indicates  the  number  ol 
bytes  to  lollow 


Figure  A-35   Format  of  a  Module  Name  Item  Type  (1) 


A. 5. 3. 2  Global  Symbol  Item  Type  (2)  -  One  type  2  item  must  appear  for 
each  global  syabol  definition  that  the  language  processor  wants  the 
debugger  to  understand.  It  need  not,  however,  include  definitions 
generated  for  the  language  processor  run-time  system. 

The  format  of  the  global  symbol  item  type  is  shown  in  Figure  A-36. 
15  8  7  0 


LENGTH 


ITEM  TYPE   2 


SYMBOL  NAME 
(RADIX-50) 


VALUE- 


DESCRIPTOR  ADDRESS  FOR  CONTAINING 
OVERLAY  SEGMENT* 


MUST  BE  ZERO 


FLAGS 


FULL  SYMBOL  NAME' 


1  Counted  ASCII  string  of  the  required  length  A  counted  ASCII 
string  Is  a  byte  string  in  which  the  first  byte  indicates  the  number  of 
bytes  to  follow. 

ZK.  1053-82 

Figure  A-36   Format  of  a  Global  Symbol  Item  Type  (2) 
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A.  5. 3. 3  PSECT  Item  Type  (3)  -  A  concatcntttd  PSECT  has  two  bat* 
addresses:  one  for  the  whole  PSECT,  and  another  for  the  part  of  it 
that  belongs  to  this  module.  It  is  the  base  address  for  the  part  that 
belongs  to  this  module  that  may  be  used  by  a  debugger  to  convert  local 
symbol  values  to  absolute  addresses. 

The  segment  descriptor  address  is  necessary  because  PSECTs  may  move  to 
segments  other  than  the  one  in  which  it  was  placed.  This  address  is 
relevant  to  languages  that  provide  semi-automatic  overlay  generation, 
like  COBOL-11.  This  word  may  be  zero  if  the  PSECT  has  not  moved  to 
another  segment . 

The  flag  word  is  a  copy  of  the  flag  word  built  by  TKB.  It  allows  for 
identification  of  VSECTs. 

The  full  PSECT  name  may  be  needed  for  some  languages. 

The  format  of  a  PSECT  item  type  is  shown  in  Figure  A-37. 


18 


8  7 


LENGTH 

ITEM  TYPE       3 

PSECT  NAME                                

BASE  ADDRESS  OF  PSECT  IN  THIS  SEGMENT- 

BASE  ADDRESS  OF  PSECT  FOR  THIS  MODULE- 

LENGTH  OF  PSECT  FOR  THIS  MODULE" 

DESCRIPTOR  ADDRESS  FOR  CONTAINING 
SEGMENT- 

FLAG  WORD- 

FULL  PSECT  NAME' 

1  A  counted  ASCII  string  o(  the  required  length  A  counted  ASCII 
string  is  a  byte  string  in  which  the  first  byte  indicates  the  number  ol 
bytes  to  follow 

ZK.t'154  8? 

Figure  A-37   Format  of  a  PSECT  Item  Type  (3) 


A. 5. 3.4   Line-Number  or   PC  Correlation   Item   Type  (4)  -  This  item 

provid^3S  the  information  needed  to  translate  a  source  line  number  into 

a  task  image  address,  or  a  task   image   address   into  a   source  line 
number . 

The  format  of  a  line-number  or  PC  correlation  item  type   is   shown   in 
Figure  A-38. 
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8     7 


LENGTH 


ITEM  TYPE      4 


PSECT 
NAME 


START  PC 


DESCRIPTOR  ADDRESS  OF  CONTAINING  OVERLAY  SEGMENT- 


START  PAGE  NUMBER 


START  LINE  NUMBER 


STRING  OF  ONE-BYTE  ITEMS 


1    Otisel  inio  PSbCT  in  Ivpp  i'  records   absolute  address  in  type  3  records 


^K  loss  •? 


Figure  A-38   Format  of  a  Line-Number  or  PC  Correlation  Item  Type  (4) 


A. 5. 3. 5  Internal  Symbol  Name  Item  Type  (5)  -  The  internal  symbol  name 
item  allows  for  the  fact  that  a  name  may  have  more  than  one  associated 
address.  For  example,  a  COBOL  variable  may  have  three  associated 
addresses:  the  address  of  the  area  that  contains  the  data,  the 
address  of  a  CIS  descriptor,  and  the  address  of  a  picture  string. 

The  internal  symbol  name  item  is  shown  in  Figure  A-39. 


A. 5. 4   Literal  Records  (Type  4) 

Literal  records  may  take  any  form,  but  the  two-byte   header   shown   in 
Figure  A-40  must  be  present. 


A. 6   END  OF  MODULE  RECORD 

The  end-of-module  record  declares  the  end  of  an  object  module.  There 
must  be  exactly  one  end-of-module  record  in  every  object  module.  As 
shown  in  Figure  A-41,  this  record  is  one  word  long. 
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IS 


8  7 


ADDRESS  1: 


ADDRESS  2: 


LENGTH 


OFFSET  TO  NAME 


MUST  BE  ZERO 


ITEM  TYPE   5 


OFFSET  TO  DATA 


NUMBER  OF  ADDRESSES 


PSECT 
NAME 


TASK  IMAGE  ADDRESS/OFFSET  ' 


SEGMENT  DESCRIPTOR  ADDRESS* 


PSECT 
NAME 


TASK  IMAGE  ADDRESS/OFFSET  (1) 


SEGMENT  DESCRIPTOR  ADDRESS- 


ADDRESS  n: 


LANGUAGE-DEPENDENT  DATA 


SYMBOL  NAME  2 


1  Modified  by  TKB 

2  A  counted  ASCII  string  of  the  required  length  A  counted  ASCII 
string  is  a  byte  string  in  which  tne  first  byte  indicates  the  number  of 
bytes  to  follow 

ZK' 1056-82 


Figure  A-39   Format  of  an  Internal  Symbol  Name  Item  Type  (5) 
15  8  7  0 


RESERVED  (0) 


ISD  RECORD  TYPE  4 


Figure  A-40   Format  of  a  Literal  Record  Type 
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0 

RECORD         . 
TYPE             ° 

Figure   A-41      Rnd-of-ModuIe    Record    Format 
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Figures  B-1  through  B-4  illustrate  how  the  Task  Builder  (TKB)   records 

a   task   image   on  disk.   As  noted  in  the  following  sections,  parts  of 

the  task  disk  image  shown  in  these  figures  are  optional  and  may  not  be 
recorded  for  every  task  image. 

The  following  sections,  which  provide  detailed  information  on  the  task 
image  file  structure,  are  organized  as  follows: 

B.l  Label  Block  Group 

B.2  Checkpoint  Area 

B.3  Header 

B.3.1  Low-memory  Context 

B.3. 2  Logical  Unit  Table  Entry 

B.4  Task  Image 

B.4.1  Autoload  Vectors  for  Conventional  Tasks 

B.4. 2  Autoload  Vectors  for  I-  and  D-Space  Tasks 

B.4. 3  Task-Resident  Segment  Descriptor 

B.4. 4  Window  Descriptor 

B.4. 5  Region  Descriptor 

B.4. 6  Supervisor-Mode  Vector 


B.l   LAuEL  BLOCK  GROUP 

The  label  block  group  precedes  the  task  on  the  disk  and  contains  data 
that  is  needed  by  the  system  to  install  and  load  a  task  but  need  not 
reside  in  memory  during  task  execution.  This  group  consists  of  three 
parts : 

•  Task  and  resident  library  data  (label  block  0) 

•  Table  of  LUN  assignments  (label  blocks  1  and  2) 

o   The  segment  load  list  (label  block  3) 

Table  B-1  describes  the  task  and  resident  library  data.  Figure  B-5 
illustrates  how  TKB  organizes  this  data  in  label  block  0.  The  INSTALL 
processor  verifies  the  task  and  resident  library  data  when  entering 
the  tasks  into  the  System  Task  Directory  (STD)  file.  Yon  can  obtain 
the  offsets  shown  in  Figure  B-5  by  calling  the  LBLDF$  macro  that 
resides  in  macro  library  LB: [1,1]  EXEMC.MLB. 
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RELATIVE  DISK  BLOCK  0 

RELATIVE  DISK  BLOCK  2 

t 


LABEL  BLOCK  0    -  TASK  AND 
RESIDENT  LIBRARY  DATA 


LABEL  BLOCK  1  -  TABLE  OF 
LUN  ASSIGNMENTS 


LABEL  BLOCK  2  -  TABLE  OF 
LUN  ASSIGNMENTS  (OPTIONAL) 


CHECKPOINT  AREA 
(OPTIONAL) 


TASK  HEADER- 
FIXED  PART 


TASK  HEADER- 
VARIABLE  PART 


ROOT  SEGMENT 
TASK  CODE  AND  DATA 


^ 


)     LABEL  BLOCK  GROUP 


J 


HEADER 


TASK  IMAGE 


Figure    B-1      image    on    Dis)<    of    Non-Overlaid    Conventional    Task 


RELATIVE  DISK  BLOCK  0 


RELATIVE  DISK  BLOCK  1 


RELATIVE  DISK  BLOCK  2 


OVERLAY  DATA  BASE      \ 


LABEL  BLOCK  0  -  TASK  AND 
RESIDENT  LIBRARY  DATA 


LABEL  BLOCK  1  -  TABLE  OF 
LUN  ASSIGNMENTS 


LABEL  Bi  OCK  2  —  TABLE  OF 
LUN  ASSIGNMENTS  (OPTIONAL) 


CHECKPOINT  AREA 
(OPTIONAL) 


TASK  HEADER- 
FIXED  PART 


TASK  HEADER- 
VARIABLE  PART 


ROOT  SEGMENT 


OVERLAY  RUN-TIME 

SYSTEM  ROUTINES  IN 

ROOT  FOR  LIBRARY 


AUTOLOAD  VECTORS 

REGION  DESCRIPTORS 

SEGMENT  DESCRIPTORS 

WINDOW  DESCRIPTORS 


LABEL  BLOCK  GROUP 


HEADER 


\     TASK  IMAGE 


o 


y 


Figure  B-2   Image  on  Disk  of  Conventional  Non-Overlaid  Task 
Linked  to  Overlaid  Library 
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RELATIVE  DISK  BLOCK  0 


RELATIVE  DISK  BLOCK  1 


RELATIVE  DISK  BLOCK  2 


RELATIVE  DISK  BLOCK  3 


OVERLAY  DATA  BASE         i 


LABEL  BLOCK  0  -    TASK  AND 
RESIDENT  LIBRARY  DATA 


LABEL  BLOCK  1     -   TABLE  OF 
LUN  ASSIGNMENTS 


LABEL  BLOCK  2  -    TABLE  OF 
LUN  ASSIGNMENTS  (OPTIONAL! 


LABEL  BLOCK  3  -  SEGMENT 
uOAD  LIST  (OPTIONAL) 


CHECKPOINT  AREA 
(OPTIONALI 


TASK  HEADER 
FIXED  PART 


TASK  HEADER 
VARIABLE  PART 


ROOT  SEGMENT 


OVERLAY  RUM-TIME 
SYSTEM  ROUTINES  IN  ROOT 


AUTOLOAD  VECTORS 

REGION  DESCRIPTORS 

SEGMENT  DESCRIPTORS 

WINDOW  DESCRIPTORS 


OVERLAY  SEGMENT  1 
AUTOLOAD  VECTORS 


OVERLAY  SEGMENT  2 
AUTOLOAD  VECTORS 


OVERLAY  SEGMENT  N 
AUTOLOAD  VECTORS 


)    LABEL  BLOCK  GROUP 


J 


HEADER 


>     TASK  IMAGE 


Figure  B-3   Image  on  Disk  of  Conventional  Overlaid  Task 
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RELATIVE  DISK  BLOCK  0 
RELATIVE  DISK  BLOCK  1 
RELATIVE  DISK  BLOCK  2 

RELATIVE  DISK  BLOCK  3 


TASK  IMAGE     < 


LABEL  BLOCK  0   -   TASK  AND  RESIDENT  LIBRmRY  DATA 


LABEL  BLOCK  1   -   TABLE  OF  LUN  ASSIGNMENTS 


LABEL  BLOCK  2  - 
TABLE  OF  LUN  ASSIGNMENTS  (OPTIONAL) 


LABEL  BLOCK  3  -  SEGMENT  LOAD  LIST  (OPTIONAL) 


CHECKPOINT  AREA  (OPTIONAl  I 


TASK  HEADER  (UNUSED  COPY)  FIXED  PART 


TASK  HEADER  (UNUSED  COPY)  VARIABLE  PART 


TASK  ROOT   -  INSTRUCTION  SPACE 


AUTOLOAD  VECTORS  -  ISPACE  PART 


TASK  HEADER  (USER  S  COPY)  FIXED  PART 
TASK  HEADER  (USERS  COPY)  VARIABLE  PART 


TASK  STACK  AREA 


TASK  ROOT  -  DATA  SPACE 


AUTOLOAD  VECTORS        D-SPACE  PART 
REGION  DESCRIPTORS 


SEGMENT  DESCRIPTORS 
WINDOW  DESCRIPTORS 


OVERLAY  SEGMENT   1         ISPACE 
AUTOLOAD  VECTORS        ISPACE  PART 


OVERLAY  SEGMENT  1         D-SPACE 
AUTOLOAD  VECTORS  -  D-SPACE  PART 


OVERLAY  SEGMENT  2  -   l-SPACE 
AUTOLOAD  VECTORS  -  l-SPACE  PART 

OVERLAY  SEGMENT  2  ~-  D-SPACE 
AUTOLOAD  VECTORS  -    D-SPACE  PART 


^     LABEL  BLOCK  GROUP 


J 


^ 


TASK  ROOT 
l-SPACE  PART 


TASK  ROOT 
D-SPACE  PART 


OVERLAY  SEGMENT  N  ~  l-SPACE 
AUTOLOAD  VECTORS  -  l-SPACE  PART 


OVERLAY  SEGMENT  N     -  U-SPACE 
AUTOLOAD  VECTORS    -  D-SPACE  PART 


Figure  B-4   Image  on  Disk  of  Overlaid  I-  and  D-Space  Task 

Table  B-1 
Task  and  Resident  Library  Data 


Parameter 


Definition 


L$BTSK   Task  name  consisting  of  two  words   in   Radix-50   format. 
This  parameter  is  set  by  the  TASK  keyword. 

L$BPAR    Partition  name   consisting   of   two   words   in   Radix-50 
format.   This  parameter  is  set  by  the  PAR  keyword. 

(continued  on  next  page) 
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Tabic  B-1  (Cont .) 
Task  and  Msident  Library  Data 


Parameter 


Definition 


L$BSA  Starting  address  of  task.  Marks  the  lowest  task  virtual 
address.   This  parameter  is  set  by  the  PAR  keyword. 

L$BHGV    Highest  virtual  address  mapped  by  address  window  0. 

L$BMXV  Highest  task  virtual  address.  When  the  task  does  not 
have  memory-resident  overlays,  the  value  is  set  to 
L$BHGV. 

L$BLDZ  Task  load  size  in  units  of  64-byte  blocks.  This  value 
represents  the  size  of  the  root  segment. 

L$BMXZ  Task  maximum  size  in  units  of  64-byte  blocks.  This 
value  represents  the  size  of  the  root  segment  plus  any 
additional  physical  memory  needed  to  contain  task 
over  lays . 

L$BOFF  Task  offset  into  partition  in  units  of  64-byte  blocks. 
This  value  represents  the  size  of  the  mapped  array  area, 
which  precedes  the  task's  code  and  data  in  the 
partition. 

L$BWND  Number  of  task  window  blocks  less  library  window  blocks 
--  Low  byte 

L$BSYS    System  ID  --  High  byte 

L$BWND    Number  of  task  windows  (excluding  resident  libraries). 

L$BSEG    Size  of  overlay  segment  descriptors  (in  bytes). 

L$BFLG    Task  flags  word.   The  following  flags  are  defined: 

Bit    Flag  Meaning  When  Bit  =  1 

15    TS$PIC    Task  contains  posi t ion- independent  code 
(PIC)  . 

14  TS$NHD  Task  has  no  header. 

13  TS$ACP  Task  is  ancillary  control  processor. 

12  TS$PMD  Task  generates  Postmortem  Dump. 

11  TS$SLV  Task  can  be  slaved. 

10  TS$NSD  No  SEND  can  be  directed  to  task. 

9  (Not  used) 

8  TS$PRV  Task  is  privileged. 

7  TS$CMP  Task  is  built  in  compatibility  mode. 

6  TS$CHK  Task  is  not  checkpointable. 

5  TS$RES  Task  has  memory-resident  overlays. 

(continued  on  next  page) 
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Table    B-1    (Cont.) 
Task   and    Resident    Library   Data 


Parameter 


Definition 


L$BFLG 
(Cont  .) 


Bit  Flag 

4  TS$IOP 

3  TS$SUP 

2  TS$XHR 

1  TS$NXH 


Meaning  When  Bit  -  1 

Privileged  task  does  not  map  I/O  page 

Im<\ge  linked  as  supervisor-mode  library 
(R/5X-11M-PLUS  systems  only). 

Ta'jk  was  built  with  external  header 

Task  was  built  with  pool  resident 
header  (non  external) 


L$BDAT 


L$BLIB 
L$BPRI 
L$BXFR 

L$BEXT 

L$BSGL 

L$BHRB 
L$BBLK 
L$BLUN 
L$BROB 
L$BROL 
L$BRDL 
L$BHDB 
L$BDHV 
L$BDMV 
L$BDLZ 
L$BDMZ 


Throe  words  containing  the  task  creation  date  as  2-digit 
integer  values  as  follows: 

•  Year  since  1900 

•  Month  of  year 

•  Day  of  month 
Resident  library  entries. 

Task  priority  set  by  the  PRI  keyword. 

Task  transfer  address.   Used  to  initiate  a  bootable  core 
image,  for  example,  the  resident  executive. 

Task  extension  size  in  units  of   32-word   blocks.    This 
parameter  is  set  by  the  EXTT3K  keyword. 


Relative  block  number  of  segment  load  list, 
no  list  is  allocated. 

Relative  block  number  of  header. 

Number  of  blocks  in  label  block  group. 

Number  of  logical  units. 

Relative  block  number  of  R/0  image. 

R/0  load  size  in  32-word  blocks. 

Size  of  R/0  data  in  32-word  blocks. 

Relative  block  number  of  data  header. 

High  vitrual  address  of  data  window  1. 

High  virtual  address  of  data. 

Load  size  of  data 

Maximum  size  of  data 


Set  to  0  if 
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Labal 

<?'»!« 

LSBTSK 

0 

7 

LSBPAR 

4 

8 

LSBSA 

to 

LSBHQV 

12 

LSBMXV 

14 

LSBLOZ 

16 

LSBMXZ 

20 

LSBOFF 

22 

L$BWND/L$BSYS 

24 

LSBSEG 

26 

LSBFLO 

30 

LIBDAT 

32 

34 

36 

LSBLIB 

40 

42 

44 

46 

50 

52 

54 

56 

60 

62 

64 

66 

70 

• 

72 

344 

LSBPRI 

346 

LSBXFR 

350 

LSBEXT 

352 

LSBSGL 

354 

LSBHRB 

356 

LSBBIK 

360 

LSBLUN 

362 

LSBROB 

364 

LSBROL 

366 

LSBRDL 

370 

LSBHDB 

372 

LSBDHV 

374 

LSBDMV 

376 

L?BDLZ 

400 

LSBOMZ 

402 

Tnk 


Nam* 


Tiik 


Pjriition 


Bas«  addran  of  talk 


HIghait  window  0  virtual  addraii 


Highitt  virtual  addrni  in  ia>k 


Load  tilt  in  64  by  la  blocki 


Maximum  ma  in  64  by  la  blocki 


Talk  ottsat  inio  partition 

Syilem  ID.  [  Numtwf  of  window  t)locks* 


Slia  of  o"erlay  lagmant  doicnpiori 


Talk  flag  word 


Talk  craKiion  data     Yaar 


Uontfi 


Day 


Library/common 


f^ame 


Base  atklrosi  of  lit>rBry 


Highest  address  in  firit  library  window 


Highest  addren  in  library 


Library  load  size  164  byte  blocks) 


Library  maximum  size  164  liyte  blocks) 


Library  offset  into  region 


Number  of  library  window  blocks 


Size  of  library'  segment  descriptors 


Library  flag  word 


Library  creation  dale  -  Year 


■  Month 


-  Day 


RSLNAtVI 
HSLSA 

RSLHGV 

RSLIi/IXV 

RSLLDZ 

RSLfUXZ 

RSLOFF 

RSLWND 

RSLSEG 

RSLFLG 

RSLDAT 


Lilirdry 

fto<|ueit 

(maximum 

of  7 

14  word 

entries  in 

RSX  11M  systems 

.itui 

maximum 

of  15 

14  word 

entries  in 

RSX  DM-nyitemi) 


Task  priority 


Task  transfer  a<ldrDSS 


Task  exiensior  (64  byte  blocks) 


Block  number  of  segment  load  list 


Block  number  of  header 


Number  of  blocks  in  l»ibel 


Number  of  lot,iCal  units 


Relative  block  of  R-0  image 


R'O  load  si?e 


R'O  data  size  m  32-word  blocks 


Relalive  block  number  of  data  headei 


High  virtual  address  of  data  window  1 


High  virtual  address  of  data 


Lojd  size  of  data 


Maxirnum  size  of  datr 


*  Less  library  window  blocks. 


Figure  B-5   Label  Block  0  —  Task  and  Resident  Libirary  Data 

Table  B-2  describes  the  contents  of  the  resident   shared  region   name 

block.    TKB   constructs   this  block  by  referring  to  the  disk  image  of 

the  resident  shared  region.    The   format   is   identical  to   words   3 
through  16  of  the  label  group  block. 
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Table  B-2 
Resident  Library/Common  Name  Block  Data 


Parameter 


Definition 


R$LNAM 

R$LSA 

R$LHGV 

R$LMXV 

R$LLDZ 

R$LMXZ 

R$LOFF 

R$LWND 
R$LSEG 
R$LFLG 


R$LDA': 


Shared  region  name  consisting  of  2  words  in  Radix-^0 
format . 

Base  virtual  address  of  library  or  common. 

Highest  address  mapped  by  fir3t  library  window. 

Highest  virtual  address  in  library  or  common. 

Shared  region  load  size  in  64-byte  blocks. 

Library  maximum  size  in  64-byte  blocks.  This  value 
represents  the  size  of  the  root  segment  plus  the  sum  of 
all  memory-resident  overlays. 

Si^e  of  mapped  array  space  allocated  by  resident 
library.  This  value  is  added  to  the  mapped  array  area 
of  the  task. 

Number  of  window  blocks  requited  by  library. 

Size  of  library  overlay  segment  descriptors  in  bytes. 

Library  flags  word.   The  following  flags  are  defined: 


Bit 
15 

14 
13 
3 
2 


Meaning 

LD$ACC  --  Access  intent  ( l=read/wr i te , 
OTead-only) 

LD$RSV  —  APR  was  reserved 

LD$CLS  --  Library  is  part  of  a  cluster 

LD$SUP  —  Supervisor-mode  library  (l=yes) 

LD$REL  --  Posi  t  ion- indepe.ndent  code  (PIC)  flag 
(1=PIC) 


LD$TYP  —  Shared  region  type  (1 
0  =  library) 


common , 


Three  words  containing  the  shared  region   creation   date 
in  2-digit  integer  va'.ues  as  follows: 


•  Year  since  1900 

•  Month  of  year 

•  Day  of  month 


The  table  of  LUM  assignments,  illustrated  in  Figure  B-6,  contains  the 
name  and  logical  ur.it  number  of  each  device  assigned.  Label  block  2 
(the  second  block  of  LUN  assignments)  is  allocated  only  if  the  number 
of  LUNs  exceeds  128. 
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TKB  cr«tt«S  the  segment  load  list  if  the  image  contains  only 
memory-rssldent  overlays.  The  segment  load  list  is  used  only  in 
RSX-llS  systems  for  loading  tasks  that  have  resident  overlays.  Figure 
B-7  illustrates  the  segment  load  list.  Each  entry  in  the  list  gives 
the  length,  in  bytes,  of  a  memory-resident  overlay  segment. 


Device  name 

LUN  1 

Label 
Block 

1 

Unit  number 

• 
• 
• 

Device  name 

LU(M  128 

Unit  number 

Device  name 

LUN  129 

Label 
Block 
2 

Unit  number 

• 
• 
• 

Device  name 

LUN  255 

Unit  number 

ZK.476'ei 


Figure  B-6   Label  Blocks  1  and  2  —  Table  of  LUN  Assignments 


Length  of  root  segment 


Length  of  first  overlay  segment 


Length  of  second  overlay  segment 


/K-477.81 

Figure  B-7   Label  Block  3  —  Segment  Load  List 


B.2   CHECKPOINT  AREA 

The  checkpoint  area  is  created  by  the  /AL  switch  (re*'er  to  Chapter 
10) .  The  checkpoint  area  is  as  large  as  the  task  image  plus  any  areas 
created  by  the  EXTTSK,  PAR,  or  VSECT  options.  The  checkroint  area 
does  not  include  space  for  the  external  header  if  the  /XH  switch  was 
speci  f ied . 
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B.3   HEADER 

As  ahown  In  rigurns  B-1  through  B-4,  the  task  h««d«r  Itacts  on  a  block 
boundary  and  is  immediately  followed  by  the  task  Image.  The  header  is 
read  into  memory  with  the  task  image. 

The  header  is  divided  into  two  parts:  a  fixed  part  js  shown  in  Figure 
B-8;  and  a  variable  part  as  shown  in  Figure  B-"?.  The  offsets  for  the 
fixed  part  are  defined  by  macro  HDRUF$  residing  in  LB:  ( 1 , 1 )  EXEMC.'iLB. 

Tne  variable  part  of  the  header  contains  win(1ow  blocks  that  describe 
the  following: 

•  The  task's  virtual-to-physical  mapping 

•  Logical  unit  data 

•  Task  contexc 

Although  the  header  is  fully  accessible  to  the  task,  you  should 
consider  only  the  information  in  the  low-memory  context  fH.DSW  through 
H.VEXT)  in  the  fixed  part  of  the  header  to  be  accurate.  In  a  mapped 
system,  the  Executive  copies  the  header  of  an  active  task  to  protected 
memory.  Subsequent  Executive  updates  to  the  header  are  made  to  this 
copy,  not  to  the  header  copy  within  the  running  task. 

The  following  sections  provide  more  detail  on  the  low-memory  context 
and  on  Logical  Unit  Table  entries  (the  Logical  Unit  Table  is  part  of 
the  variable  par   of  the  header;   see  Figure  B-9) . 

NOTE 

To  save  the  identification,  you  should 
move  the  initial  value  set  by  the  Task 
Builder  to  local  storage.  When  the 
program  is  fixed  in  memory  and  being 
restarted  without  being  reloaded,  you 
must  test  the  reserved  program  words  for 
their  initial  values  to  determine 
whether  the  contents  of  R3  and  R4  should 
be  saved. 

The  contents  of  RO ,  r;l,  and  R2  are  only 
set  when  a  debugging  aid  is  included  in 
the  task  image. 


B.3.1   Low-Memory  Context 

The  low-memory  context  for  a  task  consists  of  the  Directive  Status 
Word  and  the  impure  area  vectors.  TKB  recognizes  the  following  global 
names : 

Name  Meaning 

.FSRPT  File  Control  Services  work  area  and  buffer  pool  vector 

$OTSV  FORTRAN  OTS  work  area  vector 

N.OVPT  Overlay  run-time  system  work  area  vector 

$VEXT  Vector  extension  area  pointer 


B-10 


# 


DETAILED  TASK  IMAGE  FILE  STRUCTURE 


UM 

OKwt 

H.CSP 

0 

H  HDLN 

2 

H.EFLM 

4 

6 

HCUIC 

10 

H.DUtC 

12 

H.IPS 

14 

H.IPC 

16 

H.ISP 

20 

H.ODVA 

22 

HOOVL 

24 

HTKVA 

26 

H.TKVL 

30 

H.PFVA 

32 

H.FPVA 

34 

H.RCVA 

36 

H.EFSV 

40 

H  FPSA 

42 

H.WND 

44 

H.DSW 

46 

H.FCS 

50 

H.FORT 

52 

H.OVLY 

54 

H.VEXT 

56 

H.SPRI/H.NML 

60 

H.RRVA 

62 

64 

66 

70 

H.GARD 

72 

H.NLUN 

74 

Current  Stack  Pointer  (R61 


Header  lungth 


Event  flag  mask 


Event  flag  addreii 


Current  UIC 


Default  UIC 


Initial  PS 


Initial  PC  (R7) 


Initial  Stack  Pointer  (R6| 


ODT  SST  vector  address 


ODT  SST  vector  length 


Task  SST  vector  address 


Task  SST  vector  length 


Power  fail  AST  control  block 


Floating  point  AST  control  block 


Receive  AST  control  block 


Address  of  event  flag  context 


Address  of  floating  point  context 


For  RSX-11M-PLUS 


HSf^AP 

HDMAP 

The  H.EFLM  word  becomes  the  two 
bytes,  H  SMAP  and  H  DMAP.  the 
supervisor  node  and  I-  and 
D-space  mapping  masks. 


<4iA 


Pointer  to  number  of  window  blocks 


Directive  Status  Word 


Address  of  FCS  impure  stoi  ige 


Address  of  FORTRAN  impure  storage 


Address  of  overlay  impure  storage 


Address  of  impure  vectors 


Mailbox  LUN 


Swapping  priority 


Receive  by  reference  AST  control  block 


Reserved 


H  X25 


Reserved 


Reserved 


Header  guard  word  pointer 


Number  of  LUNs 


Low  Core 
Context 


Figure  B-8   Task  Header,  Fixed  Part 


The  only  proper  reference  to  these  pointers  is  by  symbolic  nar.ie.  The 
pointers  are  read-only.  If  you  write  into  them,  the  result  will  be 
lost  on  the  next  context  switch. 

The  impure  area  pointers  contain  the  addresses  of  the  storage  used  by 
the  reentrant  library  routines  listed  above. 
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Th«  addrcsu  cc  <taln«d  in  the  vector  extension  pointer  locates  an   area 
of  memory  that  can  contain  additional  impure  area  pointers. 


H.LUN      LUN  Table  (2  word!  per  LUN) 


Number  of  window  blocki 


Partition  control  block  addreti 


Low  virtual  address  limit 


High  virtual  address  limit 


Address  of  attach. nent  descriptor 


Window  size  (In  32  word  blocks) 


Offset  into  partition  (in  32word  blocks) 


Number  of  PDRs  to  Map 


Contents  of  last  PDR 


First  PDR  Address 


Offsets 

WBPCB 

W.BLVR 

W.BHVR 

WBATT 

W.BSIZ 

W.BOFF 

W.BNPD/W.BFPD 

W.BLPD 


Current  PS 

Current  PC 

Initial  Values 

Current  R5 

Relative  block  number  of  header 

Current  R4 

Ident.  word  #2 

Current  R3 

Ident.  word  a1 

Current  R2 

Task  name  word  #2 

Current  R1 

Task  name  word  #1 

Current  RO 

Program  transfer  address 

Header  guard  word 

7t<-479»l 


Figure  B-9   Tasl<  Header,  Variable  Part 


Figure  B-IO  illustrates  the  format  of  the  vector  extension  area.  Each 
location  within  this  area  contains  the  address  of  an  impure  storage 
area  that  can  be  ref  rred  to  by  subroutines  within  a  resident  library; 
these  subroutines  i.iust  be  reentrant.  The  address  of  this  area 
(location  $VEXTA)  is  contained  at  absolute  address  $VEXT  in  the  tas)< 
header.  Addresses  below  $VEXTA,  referred  to  by  negative  offsets,  are 
reserved  for  DIGITAL  applications.  Addresses  above  $VEXTA,  referred 
to  by  positive  offsets,  are  allocated  for  user  applications. 
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SVEXT 


SVEXTA 


» 


.PSECT  $$VEXO 


,PSECT$$VEX1 


Reserved  for 
DIGITAL  use 


Reserved  for 
user  applications 


/K  460  ai 


Figure  D-10   Vector  Extension  Area  Format 

The  program  sections  $$VEXO  and  $$VEX1  have  the  attributes  D,  GBL,  RW, 
REL,  and  OVR. 

The  program  section  attribute  OVR  facilitates  defining  the  offset  to 
the  vector  and  initializing  the  vector  location  at  link  time.  For 
example : 

.GLOBL   $VEXTA     ;   MAKE  SURE  VECTOR  AREA  IS  LINKED 

.PSECT   $$VEX1,U,GBL,REL,0VR 

$$$=.  ;   POINT  TO  BASE  OF  POINTER  TABLE 


.BLKW    N 


;   OFFSET  TO  CORRECT  LOCATION 
;   IN  VECTOR  AREA 


LABEL:  .WORD    IMPURE     ;   SET  IMPURE  AREA  ADDRESS 

OFFSET==LABEL-BEG  ;   DEFINE  OFFSET 


.PSECT 


IMPURE: 


You  should  centralize  all  offset  definitions  within  a  single  module 
from  which  the  actual  vector  space  allocation  is  made.  Also,  you 
should  write  the  source  code  with  conditional  statements  to  create  two 
object  modules:  one  that  reserves  the  vector  storage;  and  one  that 
defines  the  global  offsets  that  will  be  referred  to  by  your  resident 
library's  subroutines. 

Note  that  the  sequence  of  instructions  above  intentionally  redefines 
the  global  symbol.  The  Task  Builder  reports  an  error  if  this  value 
differs  from  the  centralized  definition. 
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You  can  locate  your  vector  through  a  ••qu*nce  of  instructiona   similar 
to  the  fol lowl ng  : 


MOV  9#VKXT,R0 
MOV  OFFSKT{R0) ,R0 
.END 


;  GET  ADDRESS  OF  VECTOR  EXTENSIONS 
;  POINT  TO  IMPURE  AREA 


B.3.2   Logical  Unit  Table  Entry 

Figure  B-11  illustrates  the  format  of  each  entry  in  the   Logical   Unit 
Table. 


UCB  address 


Window  block  pointer 


Figure  B-11   Logical  Unit  Table  Entry 


The  first  word  contains  the  address  of  the  device  unit  control  block 
in  the  Executive  system  tabler;.  That  block  contains  device-dependent 
information. 

The  second  word  is  a  pointer  to  the  window  block  if  the  device  is  file 
structured . 

The  UCB  address  is  set  during  task  installation  if  a  corresponding  ASG 
parameter  is  specified  at  task-build  time.  You  can  also  set  this  word 
at  run  time  with  the  Assign  LUN  Directive  to  the  Executive. 

The  window  block  pointer  is  set  when  a  file  is  opened  on  the  device 
whose  UCB  address  is  specified  by  word  1.  The  window  block  pointer  is 
cleared  when  the  file  is  closed. 


B.4   TASK  IMAGE 

The  system  reads  the  task  image  into  memory  beginning  with  the  task 
header  (see  Figures  B-I  thirough  B-4).  The  root  segment  of  a 
conventional  task  image  is  a  set  of  contiguous  disk  blocks;  it  is 
therefore  loaded  with  a  single  disk  access.  However,  an  I-  and 
D-space  task  root  contains  2  sets  of  contiguous  blocks.  Therefore,  an 
I-  and  D-space  task  requires  two  disk  accesses,  one  for  the  D-space 
part  and  one  for  the  I-space  part.  The  D-space  part  is  loaded  first. 
Additionally,  each  segment  of  an  overlaid  I-  and  D-space  task  requires 
two  disk  accesses  if  it  contains  both  I-  and  D-space. 

Each  overlay  segment  of  the  task  image  begins  on  a  block  boundat_  (see 
Figure  B-3) .  Note  that  a  given  overlay  segment  occupies  as  many 
contiguous  disk  blocks  as  it  needs  to  supply  its  space  request.  The 
maximum  size  for  any  segment,  including  the  root,  is  32K  minus  32 
words.  — 
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NOTE 

On*  exception  to  the  block  boundary 
alignment  of  segments  occurs  when  shared 
regions  contain  resident  overlays.  When 
this  occurs,  the  image  is  comprossed 
and,  instead  of  being  aligned  on  block 
boundaries,  segments  are  aligned  on 
32-word  boundaries.  This  facilitates 
the  loading  of  regions. 


Figures   B-12   and   n-13   illustrate   the   structure 
components  of  the  task-resident  overlay  data  base. 
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Window  descriptors  are  necessary  (or  the 
windows  that  the  Overlay  Run-T  me 
System  uses  to  map  memory  resident 
overlays   The  Overlay  Run-Time  System 
also  needs  window  descriptors  to  map 
disk-resident  overlays  that  are  up-tree 
from  memory-resident  overlay  segments. 

The  Overlay  Run-Time  System  uies 
region  descriptors  to  map  overlaid 
libraries. 


Figure  B-12   Task-Resident  Overlay  Data  Base 
for  a  Conventional  Overlaid  Task 
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Window  descriptors  are  necessary  for  the 
windows  that  the  Overlay  Run-Time 
System  uses  tc  map  memory  resident 
overlays.  The  Overlay  Run-Time  System 
also  needs  window  descriptors  to  map 
disk-resident  overlays  that  are  up-tree 
from  memory-resident  overlay  segments. 

The  Overlay  Run-Time  System,  uses 
region  descriptors  to  n-    p  overlaid 
libraries. 


Figure  B-13   Task-Resident  Overlay  Data  Base 
for  an  I-  and  D-Space  Overlaid  Task 


Autoload  vectors  are  generated  whenever  a  reference  is  made  to  an 
autoloadable  entry  point  in  a  segment  located  farther  away  from  the 
root  than  the  segment  making  the  reference. 

One  segment  descriptor  is  generated  for  each  overlay  segment  in  the 
task  ot  shared  region.  The  segmerL  descriptor  contaifs  rnform?tion  on 
the  size,  virtual  address,  and  location  of  the  segment  within  the  task 
imaqt>  file.  In  addition,  it  contains  a  set  of  link  words  that  point 
to  other  segments.  The  overlay  structure  determines  the  link  word 
contents . 


• 
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Segment  descriptors  for  I-  and  D-space  tasks  have  an  extension  for  the 
D-space  part  that  contains  the  disk  block  address,  virtual  load 
address,  segment  length  in  bytes,  and  window  pointer. 

The  window  descriptor  contains  information  required  to  issue  the 
mapping  directives.  TKB  allocates  one  window  descriptor  for  each 
memory-resident  overlay  in  the  structure. 

The  region  descriptor  contains  information  required  to  attach  a 
resident  library  or  common  block.  There  is  one  region  descriptor  for 
each  shared  region  containing  memory-resident  overlays. 

The  following  sections  describe  each  data  base  component  in  greater 
detai 1 . 


B.4.1   Autoload  Vectors  for  Conventional  Tasks 

The  autoload  vector  table  consists  of  one  entry   (put   into   the   task 
imac,e  for  each  autoload  entry  point)  in  the  form  shown  in  Figure  B-14. 


9 


JSR  PC.@.NAUTO 


PC  RELATIVE  OFFSET  TO    NAUTO 


SEGMENT  DESCRIPTOR  ADDRESS 


ENTRY  POINT  ADDRESS 


ZK1O70-8P 

Figure  B-14   Autoload  Vector  Entry  for  Conventional  ?asks 


The  autoload  vector  executes  an  indirect  JSR  instruction  to  $AUTO 
through  .NAUTO.  Following  the  JSR  instruction  is  a  pointer  to  the 
descriptor  for  the  segment  to  be  loaded.  Following  the  descriptor  is 
the  real  address  of  the  required  entry  point. 


B.4.2  Autoload  Vectors  for  I-  and  D-Space  Tasks 

The  autoload  vector  table  consists  of  two  entries  (put  into  the  task 
image  for  each  autoload  entry  point)  in  the  form  shown  in  Figure  B-15. 

The  I-space  part  of  the  autoload  vector  contains  a  MOV  instruction 
that  places  the  address  of  the  D-space  part  of  the  vector  on  the 
steck.  The  vector  then  executes  an  indirect  JMP  to  $AUTO  through 
.NAUTO.  The  D-space  part  of  the  vector  contains  the  segment 
descriptor  address  and  the  entry  point  address  of  the  reouired 
routine. 
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MOV  (PC)..  -(SP) 


ADDRESS  OF  PACKET  (D-SPAv  ^) 


JMP  (d  NAUTO 


PC  RELATIVE  OFFSET  TO    NAUTO 


l-SPACE  PORTION 


ADDRESS  OF  SEGMENT  DESCRIPTOR 


ENTRY  POINT  ADDRESS 


D-SPACE  PORTION 

ZK.107(-82 

Figure  B-15   Autoload  Vector  Entry  for  I-  and  D-Space  Tasks 

B.4.3   Segment  Descriptor 

The  segment  descriptor  for  a  conventional  task  consists  of  a  fixed 
part  and  two  optional  parts.  The  fixed  part  is  six  words  long.  If 
the  manual-load  feature  is  used  ($LOAD) ,  two  words  are  added 
containing  the  segment  name.  When  a  memory-resident  overlay  structure 
is  included,  a  ninth  word  is  appended  that  points  to  the  window 
descriptor , 

The  segment  descriptor  for  an  I-  and  D-space  task  consists  of  a   fi:ced 

part   that   is  9  words  long  and  an  optional  part  that  is  4  words  long. 

This  optional  part  is  always  present  for  task  segments  and  not  present 
for  library  segments. 

Figure  B-16  illustrates  the  contents  of  the  segment  descriptor. 
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TASK-RESIDENT  SEGMENT  DESCRIPTOR  OFFSETS 
15  12     11  0 


FLAGS 


RELATIVE  DISK  BLOCK  ADDRESS 


VIRTUAL  LOAD  ADDRESS  OF  SEGMENT 


LENGTH  OF  SEGMENT  IN  BYTES 


LINK  UP 


LINK  DOWN 


LINK  NEXT 


SEGMENT  NAME  (2-WORD  RADIX  50) 


WINDOW  DESCRIPTOR  ADDRESS 


BYTE 
0 
2 
4 

6 
10 
12 

14 
20 


FLAGS:  15-TASK  RESIDENT  FLAG  (ALWAYS  1) 

14-SEGMENT  HAS  DISK  ALLOCATION  (1  NO) 
13-SEGMENT  IS  LOADED  FROM  DISK  (1  YES) 
12-SEGMENT  IS  LOADED  AND  MAPPED  (0  YES) 

F:  0-SEGMENT  FOR  I-  AND  D-SPACE  TASK  (1  YES) 


TASK-RESIDENT  SEGMENT  DESCRIPTOR  EXTENSION 
OFFSETS  FOR  I-  AND  D-SPACE  TASKS  ONLY 


15                     12 

11                                                                   0 

UNUSED 

D-SPACE  DISK  BLOCK  ADDRESS 

D-SPACE  VIRTUAL  LOAD  ADDRESS 

D-SPACE  SEGMENT  LENGTH  IN  BYTES* 

D-SPACE  WINDOW  DESCRIPTOR  ADDRESS 

•ZERO  IF  ONLY  l-SPACE  SEGMENT 


Figure  B-16   Segment  Descriptor 

Word  0  contains  the  relative  disk  address  in  bits  0  through  11  and  the 
segment  status  in  bits  12  through  15.  Each  segment  in  the  task  image 
file  begins  on  a  disk  block  boundary.  The  relalive  disk  address  is 
the  block  number  of  the  segment  relative  to  the  start  of  the  root 
segment.   The  segment  status  flags  are  defined  as  follows: 


Bit 
15 
14 

13 

12 


Setting 


Always  set  to  1 


0  =  Segment  has  disk  allocation. 

1  =  Segment  does  not  have  disk  alloca   on. 


0  =  Segment  is  not  loaded  from  disk, 

1  =  Segment  is  loaded  from  disk. 


0  =  Segment  is  loaded  and  mapped. 

1  =  Segment  is  either  not  loaded  or  not  mapped 
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Word  1  contains  the  .'.oad  address  of  the  segment.  This  address  is  the 
first  virtual  address  of  the  area  where  the  segment  will  be  loaded. 

Word  2  specifies  the  length  of  the  segment  in  bytes. 

Words  3,  4,  and  5  point  to  the  following  segment  descriptors: 

•  Link  up  --  The  next  segment  away  from  the  root  (O  =  none)  . 

•  Link  down  --  The  next  segment  toward  the  root  (O=none) . 

•  Link  next  —  The  adjoining  segment;    the   link-next   pointers 
are  linked  in  circular  fashion. 

When  the  system  loads  a  segment,  the  overlay  run-time  system  follows 
the  links  to  determine  which  segments  are  being  overlaid  and  should 
therefore  be  marked  out  of  memory.   For  example: 


A21 


A22 


Al 


A2 


AO 
The  segment  descriptors  are  linked  as  follows: 
A21     A22         A21      A22 


s 


A21  -    ^-A?? 


Al     A2 

t 

AO 
link  up 


Al 


If 
A2 


If 
AO 


link  down 


Al  "   ^A2 

O 


link  next 


If  there  is  a  co-tree,  tne  link  next  for  the  root   segment   descriptor 
points  to  the  co-tree  root  segment  descriptor. 

Words  6  and  7  contain  the  segment  name  in  Radix-50  format. 

Word  8  points  to   the   wind'^w  descriptor   used   to   map   the   oegment 
(O  =  none)  . 


B.4.4  Window  Descriptor 

TKB  allocates  window  descriptors  only  if  you  define  a  structure 
containing  memory-resident  overlays.  Figure  B-17  illustrates  the 
format  of  a  window  descriptor.  , 

Words  0  through  7  constitute  a  window  descriptor  in  the  format 
required  by  the  mapping  directives.  If  the  memory-resident  overlay  is 
paLt  of  the  task,  the  region  ID  is  0.  If  the  memory-resident  overlay 
is  part  gI  a  shared  region,  the  overlay  loading  routine  fills  in  the 
ID  at  run  time. 

Words  8  and  9  contain  additional  data  that  is  referred  to  by  the 
overlay  routines.  Bit  15  of  the  flags  word,  if  set,  indicates  that 
the  window  is  currently  mapped  into  the  task's  address  space. 
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Word  9  contains  the  address  of  the  associated  region  descriptor.  Ii. 
the  memory-resident  overlay  is  part  of  the  task,  and  m  region 
descriptor  is  allocated,  this  vaiue    is  0. 

Word 


15 


8   7 


0 
1 
2 
3 
4 
5 
6 
7 
8 
9 


Base  Active  Page  Register 


Window  ID 


Virtual  base  address 


Window  size  in  64  byte  blocks 


Region  ID 


Offset  in  partition 


Length  to  map 


Status  word 


Send/receive  buffer  address  (always  0) 


Flags  word 


Address  of  region  descriptor 


2K-4e5-81 


Figure  B-17   Window  Descriptor 


B.4.5   Region  Descriptor 

The  region  descriptor  is  allocated  only  when  the  memory-resident 
overlay  structure  is  part  of  a  shared  region.  Figure  B-18  illustrates 
the  format  of  a  region  descriptor. 

Word 
0 
1 
2 
3 
4 
5 


7 
8 


Region  ID 


Size  of  region 


Region 
name 


Region 
partition 


Region  status 


Protection  codes  (always  0) 


Flags 


ZK-486-81 


Figure  B-18   Region  Descriptor 
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Words  0  through  7  constitute  a  region  descriptor  in  the  format 
required  by  the  mapping  directives.  The  flags  word  is  referred  to  by 
the  overlay  load  routine.  Bit  15  of  the  flags  word,  if  set,  indicates 
that  a  velid  region  identification  is  in  word  0.  If  this  bit  is 
clear,  the  overlay  load  routine  issues  an  Attach  Region  directive 
(with  protection  code  set  to  0)  to  obtain  the  identification. 
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, C.l   INTRODUCTION 

■i 

You  can  build  a  task  on  one  system  (the  host),  and  run  it  on  another 
(the  target).  For  example,  your  installation  might  consist  of  one 
large  computer  sybtem  with  mapping  hardware,  and  several  smaller 
unmapped  systems.  On  the  large  system  you  could  create  and  debug 
tasks,  and  then  transfer  them  to  the  smaller  systems  to  run. 

For  example,  if  you  are  developing  a  task  named  TK3,  using  the  default 
partition  of  your  host  system,  the  TKB  command  could  be: 

>TKB  TKi,TK3=SQl,SQ2 

When  you  are  ready  to  move  TK3  to  a  target  system,  you  build  it  again, 
indicating  the  mapping  status  of  the  target  system  and  naming  the 
partition  in  which  the  task  is  to  reside: 

>TKB 

TKB>TK3/-MM,TK3=SC1 , SQ2 

TKB>/ 

Enter  Options: 

TKB>PAR=l^ARTl:  100000:40000 

TKB>// 

The  resulting  task  image  is  ready  to  run  on  the  unmapped  target 
system. 

You  can  transfer  a  task  from  the  host  system  to  the  target  system  by 
following  these  steps: 

1.  Build  the  task  image  specifying  the  partition  in  which  the 
task  will  run.  If  the  target  system  is  an  unmapped  system, 
specify  the  partition's  base  address  and  size. 

2.  Ensure  that  any  shared  regions  accessed  by  the  t'.sk  are 
present  in  both  systems. 

3.  If  the  target  system  and  the  host  system  do  not  have  the  same 
mapping  status,  set  the  Memory  Management  switch  (/MM  or 
/-MM)  to  reflect  the  mapping  status  of  the  target  system. 

The  task  code  must  not  use  any  hardware  options  (FPP,  EIS,  EAE,  and  so 
forth)  that  are  not  present  on  the  target  system.  This  is 
particularly  important  if  you  are  a  FORTRAN  user  because  FORTRAN  tasks 
often  use  mathematics  routines  that  are  hardware  dependent.  (Refer  to 
the  IAS/RSX-11  FORTRAN  IV  Installation  Guide  and  the  lAS/RSX-ll 
FORTRAN  JV  User ' s  Guide  for  more  information  on  FORTRAN  Lequirements)  , 
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C.2   EXAMPLE  C-1:   TRANSFERRING  A  TASK  FROM  A  HOST  TO  A  TARGET  SYSTEM 

In  this  section,  the  resident  library  LIB  and  the  task  that  refers  to 
it,  MAIN  (from  Example  4,  Chapter  5),  are  rebuilt  to  run  on  an 
unmapped  system.  To  save  space,  only  the  Task  Builder  command 
sequences  are  shown. 

Assuming  that  the  target  system  has  a  partition  within  it  named  LIB, 
you  need  to  make  only  two  changes  to  the  original  command  sequence 
that  builds  the  library: 

1.  You  must  attach  the  negated  memory  management   switcii   (/-MM) 
to  the  image  file  specification. 

2.  You  must  specify  the  partition  base  and  length. 

The  modified  command  sequence  is  as  follows: 

TKB>LIB/-HD/PI/-MM,LIB/-WI,LIB=LIB 

TKB>/ 

Enter  Options: 

TKB>STACK=0 

TKB>PAR=LIB: 136000:20000 

TKB>// 

If  the  target  system  does  not  contain  a  partition  of  the  same  name  as 
that  of  the  shared  region,  you  must  change  the  name  of  the  shared 
region  to  match  the  name  of  an  existing  partition  in  the  target 
system.  This  is  a  requirement  of  RSX-llM;  on  RSX-llM-PLUS  systems  it 
is  not. 

Assuming  that  the  target  system  has  a  partition  named  GEN  and  that  the 
task  MAIN  is  to  run  in  that  partition  in  the  target  system,  you  must 
make  three  changes  to  the  command  sequence  that  builds  the  task  MAIN: 

1.  You  must  attach  the  negated  memory  management   switch   (/-MM) 
to  the  task  image  file  specification. 

2.  You  must  eliminate  the  APR  parameter  of  the  RESLIB  keyword. 

3.  You  must  explicitly  specify  the  base  address   and   length   of 
the  partition  in  which  the  task  is  to  reside. 

The  modified  command  sequence  is  as  follows: 

TKB>MAIN/-MM,MAIN/MA/-WI=MAIN 

TKB>/ 

Enter  Options: 

TKB>RESLIB=LIB/RO 

TKB>PAR=GEN:30100:4  0000 

TKB>// 

Example  C-1,  Part  1  shows  the  map  file  of  the  resident  library  LIB  for 
an  unmapped  system.  LIB  is  bound  to  the  partition  base  specified  by 
the  PAR  keyword  in  the  task-build  command  sequence.  Note  that  the 
shared  region  is  declared  position  independent  even  though  it  is  bound 
to  the  partition  base  136000.  The  position-independent  declaration  is 
not  necessary  in  this  example  because  the  referencing  task  MAIN  does 
not  require  the  program  section  names  witnin  the  library  in  order  to 
refer  to  it.  However,  in  applications  involving  tasks  that  require 
the  program  section  names  from  the  library,  you  must  declare  the 
library  position  independent  so  that  TKB  will  place  the  program 
sec'.ion  names  in  the  library's  symbol  definition  file. 
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Example  C-1,  Part  1   Task  Builder  Map  for  LIB.TSK 

LIB.TSK;!    Memory  allocation  map   TKB  M40.10      Page  1 

lO-DEC-82    11:50 

Partition  name  :  LIB 

Identification  :  01 

Task   UIC       :  [303,3] 

Task  attributes:  -HD,PI 

Total  address  windows:  1. 

Task   image   size   :  64.  words 

Task  address  limits:  000000  000163 

R-W  disk  blk  limits:  000002  000002  000001  00001. 

***  Root  segment:  LIB 

R/W  mem   limits:  000000  000163  000164  00116. 
Disk  blk  limits:  000002  000002  000001  00001. 

Memory  allocation  synopsis: 

Section  Title   Ident   File 

.  BLK. : (RW, I,LCL,REL,CON)  000000  000000  00000. 

AADD   : (RO,I,GBL,REL,CON)  000000  000024  00020. 

000000  000024  00020.  LIB     01      LIB.OBJ;! 

DIVV   : (RO,I,GBL,REL,CON)  000024  000026  00022. 

000024  000026  00022.  LIB     01      LIB.0BJ;1 

MULL   : (RO,I,GBL,REL,CON)  000052  000024  00020. 

000052  000024  00020.  LIB     01      LIB.OBJ;! 

SAVAL  : (RO,I,GBL,REL,C0N)  000076  000042  00034. 

000076  000042  00034.  LIB     01      LIB.OBJ;! 

SL'BB   :  (RO,I,GBL,REL,CON)  000140  000024  00020. 

000140  000024  00020.  LIB     01      LIB.OBJ;! 


Global  symbols: 

AADD    000000-R   MULL    000052-R   SUBB    000140-R 
DIVV    000024-R   SAVAL   000076-R 


***  Task  builder  statistics: 

Total  work  file  references:  368. 

Work   file   reads:  0. 

Work   file  writes:  0. 

Size  of  core  pool:  7086.  words  (27.  PAGES) 

SIZE  OF  WORD  FILE:  768.  words  (3.  PAGES) 

Elapsed  time  :  00  :00 :03 
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Example  C-1,  Part  2  shows  the  map  file  of  the  task  MAIN  tor  an 
unmapped  system.  The  task  is  bound  to  the  partition  base  30100  and 
linked  to  the  shared  region  LIB,  which  begins  at  136000. 

Example  C-1,  Part  2   Task  Builder  Map  for  MAIN.TSK 

MAIN.TSK;1    Memory  allocation  map   TKB  M40.10       Page  1 

ll-DEC-82    13:41 


GEN 

01 

[303,3] 

000274  001273  001000  00512. 

001634 


Partition  name  ; 

Identification  ; 

Task   UIC       ; 

Stack     limits; 

PRG  xfr  address; 

Total  address  windows:  2. 

Task   image   size   :  1152.  WORDS 

Task  address  limits:  00000  004327 

R-W  disk  blk  limits:  000002  000006  000005  00005, 

***  Root  segment:  MAIN 


R/W  mem   limits:  OCOOOO  004327  004330  02264 
Disk  blk  limits:  000002  000006  000005  00005. 


Memory  allocation  synopsis: 
Section 


Title   Ident   File 


.  BLK. : (RW,I,LCL,REL,CON)  001274  002620  01424. 

001274  000530  00344.  MAIN 


01 


MA  I  N.OB  J;], 


Global  symbols: 

AADD    160000-R 
DIVV    160000-R 
lO.WVB  011000 
MULL    060000-R 


SAVAL  060000-R 
SUBB  060000-R 
$CBDAT  003074-R 
$CBDMG  003102-R 


$CBDSG  003110-R 
$CBOMG  003116-R 
$CBOSG  003124-R 
$CBTA   003154-R 


$CBTMG  003132-R 
$CBVER  003116-R 
$CDDMG  003656-R 
$CDTB   003312-R 


***  Task  builder  statistics: 

Total  work  file  references:  1889, 
Work   file   reads; 
Work   file  writes; 
Size  of  core  pool; 
Size  of  work  file; 

Elapsed  time:00 : 00  :  07 


0. 

0. 

7086. 

WORDS  (27.  PAGES) 

1024. 

WORDS  (4.  PAGES) 
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The  RSX-llM/M-PLUS  Postmortem  Dump  task  (PMD)  generates  postmortem 
memory  dumps  of  tasks  that  are  abnormally  terminated.  In  addition, 
PMD  can  produce  edited  dumps,  called  snapshot  dumps,  for  tasks  that 
are  running.  Section  D.l  describes  Postmortem  Dumps  in  general; 
Section  D.2  discusses  the  specific  case  of  snapshot  dumps.  Both  types 
of  dumps  are  very  useful  debugging  aids. 


D.l   POSTMORTEM  DUMPS 

You  can  make  a  task  eligible  for  a  Postmortem  Dump 
ways : 


in 


any   of   three 


•  At  task-build  time,  by  specifying  the  /PM  switch  for  the  task 
file.   /-PM  disables  dumps;   it  is  the  default  condition. 

•  When  you  install  a  task  by  using  the  /PMD  switch  to  override 
the  taskbuild  option.  /PMD=YES  enables  dumping;  /PMD=NO 
disables  dumping. 

•  When  you  use  the  MCR  command  ABORT  (described  in  the 
RSX-llM/M-PLUS  MCR  Operations  Manual) ,  by  including  the  PMD 
switch  in  the  command  line  to  specify  a  d'lmp. 

You  should  install  PMD  in  a  4K  partition  in  which  all  other  tasks  are 
checkpointable.  This  allows  the  dump  to  be  generated  in  a  timely 
manner,  and  prevents  the  system  from  being  locked  up  while  the  dump  is 
being  generated.  PMD  can  dump  either  from  memory  or  from  the 
checkpoint  image  of  your  task.  The  PMD  is  sensitive  to  the  location 
of  the  aborted  task;  therefore,  if  the  aborted  tas  .s  checkpoinced 
during  the  dump,  PMD  switches  to  reading  the  checkpoint  image.  Once 
the  task  is  checkpointed ,  PMD  locks  it  out  of  memory  until  it  has 
completed  formatting  the  dump. 

Dumps  are  always  generated  on  the  system  disk  under  UFD  [l,4j; 
therefore,  to  avoid  errors  from  PMD,  you  must  create  a  UFD  for  [1,4] 
before  installing  the  task.  When  PMD  finishes  generatinc  the  dump,  it 
attempts  to  queue  the  dump  to  the  print  spooler  for  subsequent 
oprinting.  If  no  spooler  is  installed,  the  dump  file  is  left  on  the 
disk  and  can  be  printed  at  a  later  time  using  the  Peripheral 
Interchange  Program  (PIP,  described  in  the  RSX-11  Utilities  Manual) . 


NOTE 

Dump  files  tend  to  be  somewhat  large. 
The  dump  of  an  8K  partition  averages 
about  340  blocks.  Therefore,  if  there 
is  little  space  on  the  disk,  it  is 
important  to  print  and  delete   the   dump 
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file  without  delay.  The  prin:.  spooltr 
automatically  deletes  all  files  with  the 
type  .PMD  after  printing  then. 


Example  D-1  shows  the  contents  of  a  Postmortem  Dump  and  snapshot  dump; 
the  notes  that  follow  the  figure  are  keyed  to  the  figure  and  provide  a 
description  of  the  dumps  contents.   Snapshot  Dumps  are  explained   more 


fully  in  Section  D.2. 


TIME:  5-OCT-76  15:06 


Example  D-1   Sample  Postmortem  Dump  (Truncated) 

POST-MORTEM  DUMP  0 
TASK  :  TT6  ^ 

PC:  000720  Q        lOT  EXECUTION  Q 

REGS:      RO  -  000345    RJ  -  074400    R2  -  000120    R3  -  140130 
R4  -  000000    R5  -  000000    SP  -  000304    PS  -  170000 
TASK  STATUS:    MSG  AST  DST  -CHK  HLT  STP  REM  MCR  0 
EVENT  FLAG  MASK  FOR  <1-16>  000001  © 
CURRENT  UIC:  [007,001]    DSW:  l-O 

PRIORITY:  DEFAULT  -  50.   RUNNING  -  50.    I/O  COUNf:  0.    TI  DEVICE  -  TT6 :  © 
LOAD  DEVICE  -  DBO :      LBN:  1,160034  0 


FLOATING  POINT  UNIT 


STATUS  -  000000 


RO  -  000000 

Rl  -  000000 

R2  -  000000 

R3  -  000000 

R4  -  000000 

R5  -  000000 

LOGICAL  UNITS 


UNIT   DEVICE 


000000 
000000 
000000 
000000 
000000 
000000 


000000 
000000 
000000 
000000 
000000 
000000 


000000 
000000 
000000 
000000 
000000 
000000 


© 


y 


FILE  STATUS 


1 

2 
3 
4 


DBO 
DBO 
DBO 
DBO 


O 


y 


OVERLAV  SEGMENTS  LOADED  AND  RESIDENT  LIBRARIES  MAPPED 


STARTING  RELATIVE  BLOCK:  000002 
STARTING  RELATIVE  BLOCK:  000004 


BASE:  000000 
BASE:  001454 


LENGTH:  001454 
LENGTH:  000264 


TASK  STACK 

ADDRESS  CONTENTS  ASCII  RAD50 
000304   000045     %       7 


® 


TASK  IMAGE 


(continued  on  next  page) 
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Example   D-1    (Cont.)       Sample    Postmortem   Dump    (Truncated) 
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000000 
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000000 
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000000 
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! 

I 

! 
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000000 
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000001 

1 
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SIO 

A! 

000  000 
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001  000 

1 

re  Fx 

000050 

000000 

000000 
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000000 

1 

NT 

1 

000  000 

000  000 

104  002 

000  000 

1 

D 

000060 

000373 
373  000 

000000 
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000000 
000  000 

000000 
000  000 
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! 
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000000 
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! 

SJX 

D 
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000  000 
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1 
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000000 
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! 
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a: 
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! 

&S 
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000000 
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YW 
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020  156 

000  000 

377  003 

004  143 

!  n 

c 

C00130 

000020 
020  000 

000000 
000  000 

000600 
200  001 

007406 
006  017 

!   P 

IX 

BPFl 
! 
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170000 

000720 

000000 

000000 

!8P 

KX 

1 

000  360 

320  001 

000  000 

000  000 

1  P 

P 

000150 

140130 

000120 

074400 

000345 

!01 

B 

SNP 

E/1 

130  300 

120  000 

000  171 

345  000 

ixe 

P   ye 

000160 

000000 

000000 

000000 

000000 

1 

I 

000  000 

000  000 

000  000 

000  000 

1 

DUPLICATE    THROUGH    000236 


y(D 


000240 

000000 
000  000 

000000 
000  000 

001110 
110  002 

000000 
000  000 

NX 

1 

1 

H 

i 

00250 
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000000 
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TL 

DT 

1 

1 
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001612 
212  003 

074360 
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013  007 

A 

VZ 

SN 

AECl 
! 

px 
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063014 

131574 
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000000 

PMD 
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1 

014  146 

174  263 

000  000 
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3 

! 
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M3 

A 

7 
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!) 

% 
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000000 
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! 
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MS$1 
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000000 
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• 
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Q  Type  of  dump:  Postmortem  or  snapshot.  If  it  is  a  snapshot 
dutrp,  the  dump  identification  is  printed. 

©  The  name  of  the  task  being  dumped,  and  the  date  and  time  the 
dump  wjs  generated. 

0  The  program  counter  at  the  time  of  the  dump.  If  it  is  a 
Postmortem  Dump,  the  reason  the  task  was  aborted  is  printed. 

O  The  general  registers,  stack  pointer,  and  processor  status  at 
the  time  of  the  dump. 

©  The  task  status  flags  at  the  time  of  the  dump.  See  the 
description  of  ATL  or  TAL  in  the  RSX-llM/M-PLUS  MCR 
Operations  Manual  for  the  meaning  of  the  flags. 

0  The  task  event  flag  mask  word  at  the  time  of  the  dump.  If 
the  damp  is  a  snapshot  dump,  the  efn  specified  in  the  SNAP$ 
macro  will  be  ON  (see  Section  D.2.2). 

©  The  task  UIC  and  the  current  value  of  the  r'^rective  status 
word . 

©  The  task's  priority  and  default  priority,  number  of 
outstanding  I/O  requests,  and  the  terminal  from  which  the 
task  was  initiated  (TI:). 

©  The  task  load  device  and  the  logical  block  number  for  the 
start  of  the  task  image  on  the  device. 

©  The  floating-point  unit  (FPU)  registers  or  the  extended 
arithmetic  element  (EAE)  registers  if  the  task  is  using  one 
of  these  hardware  features.  If  the  task  is  not  using  the  FPU 
or  EAE,  these  registers  are  not  printed.  If  the  task  uses 
the  FPU  and  does  not  specify  /FP  on  the  task  image  file,  or 
if  it  uses  the  EAE  unit  and  has  not  specified  the  /EA  switch, 
the  registers  are  not  printed.  If  the  machine  you  are  using 
has  both  an  FPU  and  an  EAE,  PMD  assumes  you  are  using  the  FPU 
because  it  is  the  unit  of  choice  for  arithmetic  computations. 

©  I'he  logical  unit  assignments  at  the  time  of  the  dump.  UNIT 
is  the  logical  unit  number,  and  DEVICE  is  the  device  to  which 
the  logical  unit  is  assigned.  For  snapshot  dumps,  the  file 
names  of  any  open  tiles  are  displayed  under  FILE  STATUS. 
Postmortem  Dumps  do  not  display  this  information  because  all 
of  the  files  have  been  closed  as  a  result  ol  the  I/O  rundown 
on  the  aborted  task. 

©  The  following  are  displayed:  the  overlay  segments  loaded  and 
resident  libraries  mapped  at  the  time  of  the  dump;  the 
relative  block  number  of  the  segment;  '-.he  base  address;  the 
length  of  the  segment;  and,  for  tasks  using  manual  load,  the 
segment  names.  For  resident  libraries,  the  library  name  is 
also  displayed.  The  block  number  can  be  used  to  determine 
which  segment  is  loaded,  by  reference  to  the  memory 
allocation  file  generated  by  the  Task  Builder.  The  starting 
block  number  for  each  segment  is  the  relative  block  number  of 
the  segment.  By  obtaining  a  match,  you  can  determine  the 
name  of  the  segment  in  memory.  Zero-length  segments  are 
usually  co-tree  roots. 
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(E)  The  task  stack  at  the  time  of  the  dump.  The  address  is 
displayed,  along  with  the  contents,  in  octal,  ASCII,  and 
Radix-50.  Each  word  on  the  stack  is  dumped.  If  the  stack 
pointer  is  above  the  initial  value  of  the  stack  (H.ISP),  only 
one  word  is  dumped.  The  rest  is  dumped  as  part  of  the  task 
image. 

(E)  The  task  image  itself.  The  partition  being  dumped  and  the 
limits  of  interest  are  displayed.  For  Postmortem  Dumps,  all 
address  windows  in  use  are  dumped.  For  snapshot  dumps,  the 
virtual  task  limits  that  you  request  are  displayed.  The  dump 
ro>itine  rounds  the  requested  low  limit  down  to  the  nearest 
multiple  of  eight  bytes  and  rounds  the  requested  high  limit 
up  to  the  nearest  multiple  of  eight  bytes.  The  dump  image 
displays  the  virtual  starting  address  of  a  4-word  block  of 
memory,  the  data  in  both  octal  and  Radix-50  on  the  first 
line,  and  byte  octal  and  ASCII  on  the  second  lino.  A  4-word 
block  that  is  repeated  in  a  contiguous  region  of  memory  is 
printed  once,  and  then  noted  by  the  message 

***   DUPLICATE  THROUGH  xxxxxx   *** 

where  xxxxxx  indicates  the  last  word  that  is  duplicated.  If 
the  task  was  aborted,  all  address  windows  in  use  are  dumped. 
If  the  dump  is  a  snapshot  dump,  up  to  four  contiguous  blocks 
of  memory  can  be  dumped,  if  requested. 


D.2   SNAPSHOT  DUMP 

Snapshot  dumps  are  edited  dumps  produced  for  running  tasks.  You  can 
request  a  snapshot  dump  any  number  of  times  during  the  execution  of  a 
task.  The  information  generated  is  under  the  control  of  the 
programmer . 

Snapshot  dumps  are  generated  by  the  following  macros: 

•  SNPDF$  --  Defines  offsets  in  the  snapshot  dump   control   block 
and  defines  control  bits,  which  control  the  format  of  the  dump 

•  SNPBK$  --  Allocates  the  snapshot  dump  control  block  (see  Table 
D-1) 

•  SNAP$  —  Causes  a  snapshot  dump  to  be  generated 

SNPBK$  and  SNAP$  issue  calls  to  Sl«JPDF$;  so,  you  need  not  explicitly 
issue  the  SNPDF$  macro  call.  Sections  D.2.1  and  D.2. 2  describe  the 
SNPBK$  macro  and  the  SNAP$  macro,  respectively. 
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Label 


Offset 


SB.CTL 

0 

SB.DEV 

2 

SB.UNT 

4 

SB.EFN 

6 

SB.IO 

10 

SB.LM1 

(LI) 

12 

(HI) 

14 

(L2) 

16 

(H2) 

20 

(L3) 

22 

(H3) 

24 

(L4) 

26 

(H4) 

30 

SB.PMD 

32 
34 

CONTROL  FLAGS 

1 

DEVICE  MNEMONIC 

UNIT  NUMBER 

EVENT  FLAG 

SNAP  IDENTIFICATION 

MEMORY   <LOCK 

1 

LIMITS 

MEMORY  BLOCK 

. 

LIMITS 

MFMORY  BLOCK 

3 

LIMITS                                     1 

MFMORY  BLOCK 

4 

LIMITS 

"Piwn      " 

IN  RADIX-50 

D.2. 
The 

dev 


Figure  D-1   Snapshot  Dump  Control  Block  Format 

1   Format  of  the  SNPBK$  Macro 
format  of  the  SNPBKS  macro  call  is: 
SNPBK$  dev,unit,ctl,efn,id,Ll,Hl,L2,H2,L3,H3,L4,H4 


The  2-character  ASCII  name  of  the  device  to  which  the  dump  is 
directed.  If  it  is  a  directory  device,  the  UFD  [1,4]  must  be  on 
the  volume.  The  dump  is  written  to  the  disk  and  then  spooled  to 
the  line  printer.  If  there  is  no  print  spooler,  the  file  is  left 
on  the  disk.  If  the  device  is  not  a  directory  device,  the  dump 
goes  directly  to  the  device. 


unit 


ctl 


The  unit  number  of  the  device  to  which  the  dump  is  directed. 


The  set  of  flags  that  control  the  format  of  the  dump  and  the  data 
to  be  printed.   The  flags  are: 

SC.HDR      Print  the  dump  header  (items   3   to   10   in   Figure 
D-1).   Items  1  and  2  are  always  printed. 

SC.LUN      Print  information  on  all  assigned  LUNs  (item  11). 

SC.OVL     Print  information  about  all  loaded  overlay  segments 
(item  12)  . 
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SC.STK      Print  the  user  stack  (item  13). 

SC.WRD      Print  the   requested   memory   in   octal   words   and 
Radix-50  (item  14)  . 

SC.BYT      Print  the  requested  memory  in  octal  bytes  and  ASCII 
(item  14)  . 


efn 


id 


The  event  flag  to  be  used  to  synchronize  your  program  and  PMD. 

A  number  that  identifies  the  snapshot  dump.  Because  dumps  can  be 
requested  at  different  times  and  under  different  conditions,  this 
ID  is  used  to  identify  the  place  or  reason  for  the  dump. 

L1,L2,L3,L4 

The  starting  addresses  of  the  memory  blocks  to  be  dumped. 
H1,H2,H3,H4 

The  ending  addresses  of  the  memory  blocks  to  be  dumped. 

NOTE 

If  no  memory  is  to  be  dumped,  each  limit 
(L1,L2,L3,L4,H1,H2,H3,H4)  should  be  0. 

Only  one  snapshot  dump  control  block  is   allowed.    It   generates   the 
global  label  ..SPBK. 


NOTE 

Because  SNPBK$  is  used  to  allocate 
storage  for  the  snapshot  dump  control 
block,  all  arguments  except  dev  must  be 
valid  arguments  for  .WORD  or  .BYTE 
di  recti ves . 


D.2.2   Format  of  the  SNAP$  Macro 
The  format  of  the  SNAP$  macro  is: 

SNAP?  Ctl,efn,id,Ll,Hl,L2,H2,L3,H3,L4,H4 


ctl 


The  set  of  flags  that  control  the  format  of  the  dump  and  the  data 
to  be  printed.   The  flags  are: 

SC.HDR      Print  the  dump  header. 

SC.LUN      Print  information  on  all  assigned  LUNs . 

SC.STK      Print  the  user  stack. 

SC.OVL      Print   information    about    all    loaded    overlay 
segments . 
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SC.WRD      Print  the   requested   memory   in   octal   words   and 
Radix-50. 

SC.BYT     Print  the   requested   memory   in   octal   bytes   and 
ASCII. 


The  event  flag  to  be  used  to  synchronize  your  program  and  PMD.  A 
Wai t-For-Single-Event-Flag  directive  is  always  generated  to 
perform  synchronization. 


id 


A  number  that  identifies  the  snapshot  dump.  Because  dumps  can  be 
requested  at  different  times  and  under  different  conditions,  this 
ID  is  used  to  identify  the  place  or  reason  for  the  dump. 

L1,L2,L3,L4 

The  starting  addresses  of  memory  blocks  to  be  dumped. 
H1,H2,H3,H4 

The  ending  addresses  of  memory  blocks  to  be  dumped. 

NOTES 

1.  If  no  memory  is  to  be  dumped,  each  limit 
(L1,L2,L3,L4,H1,H2,H3,H4)  should  be  0. 

2.  You  can  set  the  control  flags  in  any 
combination;  they  are  not  mutually 
exclusive.  Thus,  any  number  of  options  can 
be  obtained;  for  example, 
SC.HDRISC.LUN'.SC.WRD  prints  the  header, 
LUNs,  and  the  requested  memory  in  word  octal 
and  Radix-50  mode. 

3.  Arguments  should  be  specified  only  to 
override  the  information  already  in  the 
snapshot  dump  control  block. 

4.  Because  SNAP$  generates  instructions  to  move 
data  into  the  snapshot  dump  control  block, 
its  arguments  must  be  valid  source  operands 
for  MOV  instructions. 


D.2.3   Example  of  a  Snapshot  Dump 

The  sample  program  shown  in  Example  D-2  causes  two  snapshot  dumps  to 
be  printed  directly  on  LPO:.  The  first  dump  uses  the  parameters 
defined  in  the  snapshot  dump  control  block.  The  header  is  generated, 
and  the  data  in  relative  locations  ELK  to  BLK+220  is  displayed,  in 
word  octal  and  Radix-50.   The  identification  on  the  dump  is  1. 

The  second  dump  causes  the  data  in  the  locations  BLK  to  BLK+220  to  be 

displayed   in   byte  octal  ano  ASCII.   A  header  is  also  generated.  The 

dump  identification  is  64  (100  octal).  Figures  D-3  and  D-4  show  the 
dumps  generated  by  the  sample  program. 
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6 

7 
8 
9 

10 
11 
12 


000000 
000036 
000041 
000044 

000046 
000216 
000222 
000226 
0004i2 


123 
124 
000 


116 
123 


BLK: 
120  BUF: 
124 


START: 


012700   000036' 


000004 
000046' 


.TITLE 
. I  DENT 
.MCALL 
SNPBKS 
.ASCIZ 


.EVEN 

SNAP$ 

MOV 

CALL 

SNAPS 

lOT 


SNPTST  -  TEST  SNAP  DUMP  AND  PMD 

/O  1  / 

SNPBKS, SNAPS, CALL 

LP,0,SC.HDR!SC.OVL!SC.WRD, 1 , 1 , BLK , BLK+2  20 

/SNPTST/ 


»BUF,R0 

SCATS 

ISC.HDR!SC.OVL!SC.BYT, ,1100 


.END 


START 


D 
I 
■XI 


SNPTST  -  TEST  SNAP  DUMP  AND  PMD  MACRO  MlOlO 
SYMBOL  TABLE 


BLK  OOOOOOR 

EOF  000036R 

IE.ACT=  *•»**•  GX 

SB.CTL=  000000 

SB.DEV=  000002 

.  ABS.   000000      000 
000414      001 
ERRORS  DETECTED:   0 


SB.EFN=  000006 
SB. ID  =  000010 
SB.LM1=  000012 
SB.PMD=  000032 
SB.UNT=  000004 


03-SEP-76  '5:57   PAGE  1-1 


SC.BYT=  000040 
SC.HDR=  000001 
SC.LUN=  000002 
SC.OVL=  000004 


SC.STK=  000010 
SC.WRD=  000020 
START    000046R 
SCAT5  =  »*••••  GX 


SDSW   =  *»•«••  GX 
SSST2  =  000027 
..SPBK   OOOOOORG 
...SNP=  000032 


O 

a 

3 


VIRTUAL  MEMORY  USED:   }335  WORDS   (  6  PAGES) 
DYNAMIC  MEMORY  AVAILABLE  FOR   30  PAGES 
ASSEMBLY  TIME  (ELAPSE:)):   00:00:14 
SNPTST, SNPTST=SNPTST 


Example  D-2   Sample  Program  That  Calls  for  Snapshot  Dumps 


MEMORY  DUMPS 


Example  D-3   Sample  Snapshot  Dump  (in  Word  Octal  and  Radix-50) 


SNAPSHOT  DUMP   ID:  1 
TASK:  TT6 
PC:  000522 

REGS:      RO  -  000000    Rl  -  100104    R2  -  000000 
R4  -  000000    R5  -  000000    SP  -  000304 
TASK  STATUS:    MSG  -CHK  STP  WFR  REM  MCR 
EVENT  FLAG  iiASK  FOR  1-16>  000001 
CURRENT  UIC:  (007,001)    DSW:  1. 

PRIORITY:  DEFAULT  -  50.   RUNNING  -  50.    I/O  COUNT:  0 
LOAD  DEVICE  -  DBO:      LBN:  1,160034 
FLOATING  POINT  UNIT 


TIME:  5-OCT-76  15:06 

R3  -  140130 
PS  -  170000 


TI  DEVICE 


TT6: 


STATUS 


000000 


RO  -  000000 
Rl  -  000000 
R2  -  000000 
R3  -  000000 
R4  -  OOOOOO 
R5  -  000000 


000000 
000000 
000000 
000000 
000000 
000000 


000000 
000000 
000000 
000000 
000000 
000000 


000000 
000000 
000000 
000000 
000000 
000000 


C'ERLAY  SEGi'lENTS  LOADED  AND  RESIDENT  LIBRARIES  MAPPED 

STARTING  RELATIVE  BLOCK:  000002    BASE:  000000    LENGTH:  00145v 

TASK  IMAGE 


PARTITION: 

GEN 

VIRTUAL 

LIMITS:  000304  - 

000524 

000300 

001051 

000001 

000025 

050114 

M3 

A 

U 

L36! 

000310 

000000 

000001 

000001 

000304 

A 

A 

D61 

000320 

000524 

000000 

000000 

000000 

HT 

I 

000330 

000000 

000000 

000000 

063014 

PMD! 

000340 

131574 

047123 

052120 

052123 

•  •  • 

LUK 

MSX 

MSS! 

000350 

000000 

016746 

177734 

012746 

DIN 

7T 

CTF! 

0  0  0  <  6  0 

u  0  1  0  1  7 

■  0  4-177 

103456 

005046 

MW 

U61 

UYF 

AX8! 

000370 

0127'!6 

000304 

012746 

000336 

CTP 

D6 

CTF 

EVl 

000400 

017646 

bOOOOO 

062766 

000002 

EBV 

PLV 

B! 

000410 

000002 

017666 

000002 

000002 

B 

EB8 

B 

B! 

000420 

012746 

0002507 

104377 

013435 

CTF 

31 

U61 

UX/! 

000430 

005046 

005046 

005046 

005046 

AX8 

AX8 

AX8 

AX8! 

000440 

012746 

000336 

017646 

000000 

CTF 

EV 

EBV 

! 

000450 

062766 

000002 

000002 

017666 

PLV 

B 

B 

E38! 

000460 

000002 

000002 

012746 

003413 

B 

B 

CTF 

AEC! 

000470 

104377 

103006 

022737 

177771 

U61 

UQO 

FBO 

81  ! 

000500 

000046 

00140: 

000261 

000405 

8 

SJ 

DQ 

FU! 

000510 

016746 

177576 

012746 

001051 

DIN 

5F 

CTF 

M3! 

000520 

104377 

012700 

000342 

004767 

U61 

CSH 

EZ 

AWl! 
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MEMORY  DUMPS 

Example  D-4   Sample  Snapshot  Dump  (in  Byte  Octal  and  ASCII) 

SNAPSHOT  DUMP   ID:  64 
TASK:  TT6  TIME:  5-OCT-76  lb:06 

PC:  000716 

REGS:      RO  -  000345    Rl  -  074400    R2    -    000120    R3  -  140130 
R4  -  000000    R5  -  000000    SP  -  000304    PS  -  170000 
TASK  STATUS:    MSG  -CHK  STP  WFR  REM  MCR 
EVENT  FLAG  MASK  FOR  1-16>  000001 
CURRENT  UIC:  [007001]    DSW :  1. 

PRIORITY:  DEFAULT  -  50.   RUNNING  -  50.    I/O  COUNT:  0.    TI  DEVICE  -  TT6: 
LOAD  DEVICE  -  DBO:      LBN:  1,160034 

FLOATING  POINT  UNIT 

STATUS  -  000000 

RO  -  000000  000000  000000  000000 

Rl  -  000000  000000  000000  000000 

42  -  000000  000000  000000  000000 

^  -  000000  000000  000000  000000 

R4  -  000000  000000  000000  000000 

R5  -  000000  000000  000000  000000 

OVERLAY  SEGMENTS  LOADED  AND  RESIDENT  LIF   RIES  MAPPED 

STARTING  RELATIVE  BLOCK:  000002    BASE:  000000    LENGTH:  001454 
STARTING  RELATIVE  BLOCK:  000004    BASE:  001454    LENGTH:  000264 

(continued  on  naxt  page) 
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Example  D-4  (Cont.)   Sample  Snapshot;  Dump  (in  Byte  Octal  and  ASCII) 


1 

rASK 

IMAGE 

PARTITION: 

GEN 

VIRTUAL 

LIMITS: 

000304 

-  000524 

000300 

051 

002 

001 

000 

045 

000 

114 

120 

1) 

% 

LP! 

000310 

000 

000 

001 

000 

100 

000 

304 

000 

! 

9 

D  1 

000320 

124 

001 

000 

000 

000 

000 

000 

000 

!T 

! 

000330 

000 

000 

000 

000 

000 

000 

014 

146 

1 

f  1 

000340 

174 

263 

123 

116 

120 

124 

123 

124 

!  3 

SN 

PT 

STl 

000350 

000 

000 

346 

035 

334 

377 

346 

025 

! 

f 

\ 

f  I 

000360 

037 

002 

377 

210 

056 

207 

046 

012 

! 

&  ! 

000370 

346 

025 

304 

000 

346 

025 

336 

000 

!f 

D 

f 

"  ! 

000400 

246 

037 

000 

000 

366 

145 

002 

000 

!& 

ve 

1 

000410 

002 

000 

266 

037 

002 

000 

002 

000 

1 

6 

! 

000420 

346 

025 

107 

005 

377 

210 

035 

207 

if 

G 

! 

000430 

046 

012 

046 

012 

046 

012 

046 

012 

!& 

& 

& 

&  1 

0004*0 

346 

025 

336 

000 

246 

037 

000 

000 

!f 

• 

& 

1 

0004'  1 

366 

145 

002 

000 

002 

000 

266 

037 

!ve 

6  1 

0004c0 

002 

000 

002 

000 

346 

025 

013 

007 

I 

f 

! 

000470 

377 

2in 

006 

206 

337 

045 

371 

377 

! 

% 

y  ! 

000500 

046 

000 

002 

003 

261 

000 

005 

001 

!& 

T 

! 

000510 

346 

035 

176 

J/7 

346 

025 

051 

002 

!f 

f 

)  I 

000520 

377 

210 

300 

025 

342 

000 

367 

Oil 

1 

? 

b 

w  ! 
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APPENDIX  E 
RESERVED  SYMBOLS 


Several  global  symbols  and  program  section  names^  are  reserved  for  use 
by  TKB.2  Special  handling  occurs  when  TKB  encounters  a  definition  of 
one  of  these  names  in  a  task  image. 

The  definition  of  a  reserved  global  symbol  in  the  root  segment   causes 

a   word   in   the   task  image  to  be  modified  with  a  value  calculated  by 

TKB.  The  relocated  value  of  the  symbol  is  taken  as  the  modification 
address. 

The  following  global  symbols  are  reserved  by  TKB: 

Global  Modification 

Symbol  Value 

.FSRPT    Address  of  file  storage  region  work  area  (.FSRCB). 

.MBLUN    Mailbox  logical  unit  number. 

•MOLUN    Error  message  output  device. 

.NLUNS  The  number  of  logical  units  used  by  the  task,  not 
including  the  message  output  and  overlay  units. 

.NOVLY    The  overlay  logical  unit  number. 

N.OVPT    Address  of  overlay  run-time  system  work  area  (.NOVLY). 

.NSTBL  The  address  of  the  segment  description  tables.  This 
location  is  modified  only  when  the  number  of  segments 
is  greater  than  one. 

.ODTLl     Logical  unit  number  for  the  DDT  terminal  device  TI : . 

.0DTL2  Logical  unit  number  for  the  ODT  line  printer  device 
CL:  . 


1.  In  RSX-llM  and  RSX-llM-PLUS,  absolute  sections  (ASECTs)  and  both 
blank  and  named  control  sections  (CSECTs)  are  supplanted  by  program 
sections  (PSECTs) .  The  .PSECT  assembler  directive  eliminates  the  need 
for  .ASECT  and  .CSECT  directives,  except  for  compatibility  with  other 
systems.  This  manual  refers  to  all  sections  as  program  sections, 
unless  the  specific  characteristics  of  ASECTs  or  CSECTs  apply. 

2.  All  symbols  and  program  section  names  containing  a  period  (.)  or  a 
dollar  sign  {$)    are  reserved  for  DIGITAL-supplied  software. 
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Global  Modification 

Symbol  Value 

.SUMLl  P/OS  Standard  utility  module  LUN. 

. PTLUN  Logical  unit  number  for  plotter/graphics  software. 

$OTSV  Address  of  Object  Time  System  work  area  ($OTSVA) . 

. TRLUN  The  trace  subroutine  output  logical  unit  number. 

.USLUl  Logical  unit  number  for  special  purpose  user  software. 

.USLU2  Logical  unit  number  for  special  purpose  user  software. 

$VEXT  Address  of  vector  extension  area  ($VEXTA)  . 

TKB  reserves  the  following  program  section  names.   In  some  cases,   the 
definition   of   a  reserved  program  section  causes  that  program  section 

to  be  extended  if  you  specify  the  appropriate  option. 


Source 
Location 

TKB 


TKB 


TKB 


TKB 


TKB 


Input 
Module 


Section 
Name 

$$ALER 


$$ALVC 
$$ALVD 
$$ALVI 
$$AUTO 


$$DBTS 


Description 

Contains  code  to  process  or  trap  Overlay  Run-time 
System  segment  load  errors.  Provides  named  areas 
in  the  task  for  the  FORTRAN-IV  Object  Time  System 
and  the  RSX-llM  Overlay  Run-time  System. 

Contains  the  segment  autoload  vectors  for  tasks 
without  I-  and  D-space. 

Contains  the  D-space  portions  of  the  segment 
autoload  vectors  in  an  I-  and  D-space  task. 

Contains  the  I-space  portions  of  the  segment 
autoload  vectors  in  an  I-  and  D-space  task. 

Contains  code  to  determine  if  a  called  subroutine 
in  an  overlay  segment  is  already  in  memory  or  if 
that  overlay  segment  should  be  read  into  memory 
before  control  is  passed  to  the  subroutine  that  is 
called . 

This  symbol  should  appear  in  the   debugger   input 
module  with  the  symbol  $DBTS  as  follows: 


$DBTS! 


.PSECT   $$DBTS 
.PSECT 


SYSLIB 


$$DEVT 


The  task  builder  extends  $$DBTS  and  fills  it  with 
time  stamp  information  followed  by  the  filename 
information  of  the  .STB  file. 

The  extension  length  (in  bytes)  is  calculated  from 
the  formula: 


EXT  =  <S.FDB+52>*UNITS 

The  definition  of  S.FDB  is  obtained  from  the  root 
segment  symbol  table,  and  UNITS  is  the  number  of 
logical  units  used  by  the  task,  excluding  the 
message  output,  overlay,  and  ODT  units. 
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Source 
Location 

SYSLIB 


SYSLIB 


TKB 


Section 
Name 

S$FSR1 


S$I0B1 
$$I0B2 


Description 

The  extension  of  this  section  is  specified  by  the 
ACTFIL  option. 

The  extension  of  this  option  is  specified  by  the 
MAXBUF  option. 

A  zero  lenoth  .PSECT  containing  a  label,  lOBFND, 
that  is  stu'.ed  in  the  work  area  offset,  W.BEND, 
representing  the  upper  bound  of  the  I/O  buffer, 
$$I0B1.  TKB  uses  $$I0B2  as  a  boundary  value  to 
•'  '■  -tiine  whether  the  I/O  buffer  has  overflowed. 


TKB 
TKB 


$$LOAD   0    ay  manual  load  routine. 

$$MRKS  Contains  code  to  properly  mark  those  segments  that 
are  not  needed  any  longer  or  have  been  overlaid  by 
another  segment  as  being  out  of  memory.  This 
ensures  that  c  fresh  copy  of  the  overlay  segment 
will  be  read  in  the  next  time  the  overlay  segment 
is  needed. 


SYSLIB     $$0BF1    FORTRAN  OTS  uses  this  area   to   parse   array   type 

format  specifications.  This  section  can  be 
extended  by  the  FMTBUF  keyword. 

TKB         $$0BF2    A  zero  length  .PSECT   containing   a   label,   OBFH , 

that  is  stored  in  the  work  area  offset,  W.OBFH, 
which  represents  the  upper  bound  of  the  run-time 
format  buffer,  $$0BF1.  TKB  uses  S$0BF2  to 
determine  whether  the  run-time  format  buffer  has 
over f lowed . 


TKB 


$$0VDT  The  Overlay  Run-time  System  impure  data  area.  The 
symbol  .NOVPT  in  low  memory  points  to  this  area. 
This  area  defines  the  operational  parameters  with 
which  the  Overlay  Run-time  System  operates  on 
disk-resident  and  memory-resident  overlay 
structures . 


TKB 


$$OVRS 


TKB 

TKB 

TKB 
TKB 


$$PDLS 
$$RDSG 

$$RGDS 
$$RTQ 


The  .ABS.  program  section  that  redefines  the 
Overlay  Run-time  System  impure  data  area  with 
different  symbols,  defined  as  offsets  and  relative 
to  zero.  These  offsets  are  necessary  for  proper 
linkages  between  the  subroutines  in  the  Overlay 
Run-time  System.  This  program  section  is  never 
included  in  the  memory  allocation  of  the  task 
because  of  its  absolute  program  section  attribute. 


Cluster  library  service  routine. 

Contains  the   code   that   reads 
overlay   segment  selected  by  the 
the  programs  section  SSAUTO. 


into   memory   the 
code  contained  in 


Contains   the   region   descriptors 
libraries  referred  to  by  the  task. 


tor 


resident 


Defines  the  PSECT  used  for  selective  enabling  of 
AST  recognition  in  the  Overlay  Run-time  System. 
$$RTQ  is  0  in  length  if  SAUTOT  is  not  included. 
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Source 
Locat  icp. 

TKB 


TKB 
TKB 

TKB 

TKB 
TKB 

FORTRAN 


Section 
Name 

$$RTR 


$$RTS 
$$SLVC 

$$SGDO 

$$SGD1 
$$SGD2 


Description 

Defines  the  PSECT  used  for  selective  disabling  of 
AST  recognition  in  the  Overlay  Run-time  System. 
S$RTR  is  0  in  length  if  $AL'TOT  is  not  included. 


Contains  the  return  instruction. 

Supervisor-mode    library    transfer 
(RSX-llM-PLUS  only) . 


vectors 


Contains  the  program  section   adjoining   the   task 
segment  descriptors. 

Contains  the  task  segment  descriptors. 

Contains  a  .WORD   0   following   the   task   segment 
descr  iptors . 


TKB 


$$TSKP    TKB  f   Is  in  the  following  words  in  the  PSECT: 

•  APR  bit  map  in  word  $APRMP 

•  Task  offset  into  region  in  word  $LBOFF 

•  Maximum  physical  read/write  memory   needed   for 
task  in  word  $MXLGH 

•  Maximum  physical  read-only   memory   needed   for 
task  in  word  $MXLGH+2 

•  Task  extension  in  32-word  blocks  in  word  $LBEXT 
SSWNDS    Contains  task  window  descriptors 


• 
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APPENDIX  F 
IMPROVING  TASK  BOILDER  PERFORMANCE 


This  appendix  contains  procedures  to  assist  you  in  maximizing  Task 
Builder  (TKB)  performance.   These  procedures  include: 

•  Evaluating  and  improving  TKB  throughput 

•  Modifying  command  switch  defaults  to  provide  a  more   efficient 
user  interface 

•  Using  the  Slow  Task  Builder  when   large   work   file   space   is 
required 

These  procedures  assume  that  the  program  to  be  linked  requires 
features  not  found  in  the  Fast  Task  Builder  (FTB)  described  in 
Appendix  G. 

Using  the  procedures  described  in  this  appendix  may  require  relinking 
TKB.  You  can  do  this  only  in  a  system  that  has,  as  a  minimum,  a  14K 
user-controlled  or  system-controlled  partition.  In  some  cases,  you 
can  make  the  modifications  without  relinking  by  using  the  binary  patch 
program  ZAP  (see  the  RSX-11  Utilities  Manual) . 

Modifications  to  the  TKB  build  file  imply  one  or  more  of  the  following 
files  located  under  UFD  [1,24]  (mapped)  or  [1,20]  (unmapped): 

RSX-llM  systems: 

TKBBLD.CMD 
STKBLD.CMD 

RSX-llM-PLOS  systems: 

TKBBLD.CMD 
STKBLD.CMD 

These  files  reside  on  the  disk  containing  the  utility  object  files. 


F.l   EVALUATING  AND  IMPROVING  TASK  BOILDER  THROUGHPUT 
Task  Builder  throughput  is  determined  by  three  factors: 

•  The  amount  of  disk  latency  incurred  because  of  overlays 

•  The  amounl  of  -^amory  available  for  table  storage 

•  The  amount  of  disk  latency  due  to  input  file  processing 

The  following  sections  outline  methods   for   improving   throughput   in 
each  of  these  last  two  cases. 
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F.1.1   Table  Storage 

The  principal  factor  governing  TKB  performance  is  the  amount  of  memory 
available  for  table  storage.  To  r-^duce  memory  requirements,  a  work 
file  is  used  to  store  symbol  definitions  and  other  tables.  This  work 
file  cannot  exceed  65,543  bytes.  As  long  as  the  size  of  these  tables 
is  within  the  limits  of  available  memory,  the  contents  of  this  file 
are  kept  in  memory  and  the  disk  is  not  accessed.  If  the  tables  exceed 
thi J  limit,  some  information  must  be  displaced  and  moved  to  the  disk, 
degrading  performance  accordingly. 

You  can  gauge  work  file  performance  by  consulting  the  statistics 
portion  of  the  TKB  map.   The  map  displays  the  following  parameters: 

•  Number  of  work  file  references  --  Total  number  of  times  that 
work  file  data  was  referred  to. 

•  Work  file  reads  --  Number  of  work  file  references  that 
resulted  in  disk  accesses  to  read  work  file  data. 

•  Work  file  writes  —  Number  of  work  file  references  that 
resulted  in  disk  accesses  to  write  work  file  data. 

•  Size  of  core  pool  --  Amount  of  in-core  table  storage  in  words. 
This  value  is  also  expressed  in  units  of  256-word  pages 
(information  is  read  from  and  written  to  disk  in  blocks  of  256 
words) . 

•  Size  of  work  file  --  Amount  of  work  file  storage  in  words.  If 
this  value  is  less  than  che  pool  size,  the  number  of  work  file 
reads  and  writes  is  0.  That  is,  no  work  file  pages  are 
removed  to  the  disk.  This  value  is  also  expressed  in  pages 
(256-word  blocks) . 

•  Elapsed  time  --  Amount  of  time  required  to  build  the  task 
image  and  output  the  map.  This  vali'e  excludes  ODL  processing, 
option  pr'->cessing ,  and  the  time  required  to  produce  the  global 
cross-reference. 

You  can  reduce  the  overhead  for  gaining  access  to  the  work  file  in  one 
or  more  of  the  following  ways: 

•  By  increasing  the  amount  of  memory  available  for  table  storage 

•  By  placing  the  work  file  on  the  fastest  random  access  device 

•  By  decreasing  system  overhead  required  to  gain  access  to  the 
file 

•  By  reducing  the  number  of  work  file  references 

You  can  increase  the  amount  of  table  storage  by  installing  TKB  in  a 
larger  partition  or,  if  TKB  is  running  in  a  system-controlled 
partition,  by  using  the  INSTALL/INC  keyword  to  allocate  more  space. 

In  a  system  that  includes  support  for  the  Extend  Task  directive,  TKB 
automatically  increases  its  size  if  it  is  checkpointable  and  installed 
in  a  system-controlled  partition.  You  set  the  maximum  limit.  You  can 
increase  this  maximum  by  issuing  the  MCR  command  SET  /MAXEXT. 

Increasing  the  proportion  of  resident  dynamic  memory  reduces  the 
amount  of  I/O  necessary  for  access  to  TKB  internal  data  structures. 
As  stated  above,  once  the  resident  memory  has  been  filled,  the  data 
structures   overflow  into  a  temporary  work  file  on  the  device  assigned 
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to  the  work  file  logical  unit  number.  This  logical  unit  number 
(W$KLUN)  is  specified  in  the  build  command  file.  Preferably,  this 
unit  number  should  be  assigned  to  a  device  other  than  the  system 
device,  for  example  a  fixed-head  disk. 

Displacement  of  pages  to  the  work  file  is  done  on  a  least  recently 
used  basis.  The  work  file  extends  automatically  as  necessary  to  hold 
all  pages  displaced.  The  parameter  W$KEXT  is  provided  in  the  build 
coitunand  file  of  TKB  and  defines  the  file  extension  properties.  A 
negative  value  indicates  that  the  extend  is  noncontiguous;  a  positive 
value  indicates  that  the  extend  is  contiguous.  If  a  contiguous  extend 
fails,  a  noncontiguous  request  is  attempted;  if  a  noncontiguous 
extend  fails,  a  fatal  work  file  I/O  error  is  reported.  As  long  as  the 
work  filfc  remains  contiguous,  a  higher  access  rate  can  be  obtained. 

It  is  not  possible  to  state  exactly  how  many  symbols  TKB  can  process, 
because  there  are  many  data  structures  included  in  virtual  memory. 
The  following  is  a  list  of  the  structures  that  are  stored  in  the 
virtual  memory.  All  the  sizes  given  are  approximate  only  (sizes  vary 
with  characteristics  of  the  task  being  built  and  may  vary  from  release 
to  release) . 


Structure  Name 


Description 


Approximate  Size 
(in  Words) 


Segment  Descriptor 


Contains  listhead 
sizes,  the  pointers 
defining  the  overlay 
tree,  the  segment  name, 
Part  of  this  structure 
becomes  the  segment 
descriptor  in  the 
resultant  task  image. 


80. 


P-section  Descriptor 


Contains  the  name, 
address  size,  and 
attributes  of  a 
p-section . 


10. 


Symbol  Descriptor 


Contains  symbol  name,     8. 
value,  flags,  and 
pointers  to  defining      15. 
segment  and  program 
section  descriptors. 


(nonoverlaid  task) 
(overlaid  task) 


Element  Descriptor 


Contains  module  8.-1! 

name,  ident ,  filename, 
count  of  program 
section  and  some 
flags . 


Control  Section 
Mapping  Table 


Table  of  program 
section  size  and 
program  section 
descriptor  addresses. 


Two  words  per 
program  section  in 
each  module 


The  maximum  usage  of  virtual  memory  occurs  during  phase  three  of  TKB, 
when  the  symbol  table  is  built.  However,  phase  one  makes  significant 
use  of  virtual  memory  when  an  overlaid  task  is  being  built.  It  is  at 
this  point  that  all  the  segment  descriptors  are  allocated,  as  well  as 
an  element  descriptor  for  every  file  name  encountered  during  the 
parsing  of  the  tree  description.  In  addition,  a  p-section  descriptor 
is  produced  for  every  .PSECT  directive  encountered  in  the  overlay 
description. 
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The  parsing  of  the  overlay  description  also  makes  use  of  dynamic 
memory  during  the  processing  of  each  directive.  This  memory  is 
released  upon  completion  of  the  analysis;  during  the  analysis, 
however,  the  whole  tree  description  must  fit  into  the  resident  portion 
of  the  storage.  If  sufficient  storage  cannot  be  obtained  in  the 
resident  dynamic  memory,  the  error  message  NO  DYNAMIC  STORAGE 
AVAILABLE  is  returned.  The  method  for  increasing  the  ratio  of  dynamic 
storage  to  virtual  memory  can  be  applied  here,  possibly  to  allow  a 
task  with  a  large  overlay  description  to  be  built. 

The  amount  of  memory  required  during  analysis  depends  on: 

•  The  number  of  directives 

•  The  length  of  .FCTR  lines 

•  The   number   of   operators,   that   is,   commas,   dashes,    and 
parentheses) 

•  The  number  of  file  names  encountered 

TKB  links  all  DEC-supplied  tasks  in  a  14K  partition. 

There  are  a  number  of  ways  to  reduce  the  amount  of  virtual  memory 
required  during  the  build  of  a  specific  task.  Reducing  the  data 
structures  in  virtual  memory  also  increases  the  speed  of  searching  the 
tables  and  reduces  the  amount  of  paging  to  the  work  file. 

1.  Extract  object  modules  by  name  from  relocatable  object 
libraries  (for  example.,  LIBRY/LB:M0D1 :M0D2) .  This  technique 
requires  smaller  element  descriptors  and  fewer  file  name 
descriptors  and  is  also  faster  because  there  are  fewer  files 
to  open  and  close. 

2.  Use  concatenated  object  modules  for  the  same  reasons  as 
above. 

3.  Use  shared  regions  (resident  libraries  and  common  areas)  for 
language  and  overlay  run-time  systems  and  file  control 
services.  Such  use  of  shared  regions  allows  symbols  and 
p-sections  to  be  defined  only  once,  rather  than  on  multiple 
branches  of  the  tree. 

4.  Place  modules  that  occur  on  parallel  branches  of  the  tree  in 
a  common  segment  (for  example,  closer  to  root)  for  the  same 
reasons  as  in  3  above. 

5.  Use  the  /SS  switch  on  symbol  table  files  (.STB)  that  describe 
absolute  symbol  definitions  so  that  only  those  symbols 
referenced  are  extracted  from  the  module. 

6.  Minimize  the  number  of  segments  and  keep  the  tree  balanced. 
For  example,  if  one  segment  is  very  long,  there  is  no  value 
in  putting  a  tree  structure  in  parallel  unless  creating  one 
segment  in  parallel  would  be  longer. 

In  addition  to  the  above,  a  version  of  TKB  can  be  built  which  has  less 
throughput  but  requires  less  virtual  memory  per  element  than  TKB. 
This  version  is  built  using  the  coimnand  file  STKBLD.CMD  supplied  on 
the  RK05  utility  disk,  or  the  RK06  and  RP  system  disks  under  UFD 
[1,20]  (unmapped)  or  [1,24]  (mapped). 
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There  ace  four  error  messages  associated  with  the  virtual  memory 
system: 

•  NO  DYNAMIC  STOkAGE  AVAILABLE.  This  error  occurs  when  there  is 
insufficient  resident  storage  for  creating  some  data 
structures.  As  much  as  possible  of  the  data  already  allocated 
(all  unlocked  pages)  has  been  paged  to  the  work  tile,  but 
there  is  still  not  enough  free  memory.  Such  a  situation  might 
arise  during  the  analysis  of  the  overlay  description,  early  in 
the  task-build  run,  and  particularly  if  it  is  a  complex  tree. 
Reducing  the  DDL  and  extending  the  Task  Builder  memory 
allocation  (see  above)  are  the  recommended  recovery 
procedures . 

•  UNABLE  TO  OPEN  WORKFILE.  The  probable  causes  of  this  error 
are: 

Device  assigned  to  logical  unit  8  of  the   Task   Builder   is 
not  mounted. 

The  device  is  not  FILES-11. 

There  is  no  space  on  the  volume. 

The  device  is  off  line,  not  ready,  write  locked,  or  faulty. 

There  is  no  such  device. 

The  MCR  function  LUN  ...TKB  may  be   used   to   determine   which 
device  the  Task  Builder  is  attempting  to  use. 

•  WORKFILE  I/O  ERROR.   The  probable  causes  of  this  error  are: 

Hardware  error  (for  examrie,  parity  error  on  the  disk). 

Device  is  not  ready,  or  is  wr i te-locked . 

An  extend  failure  has  occurred  (for  example,   the   disk   is 
full)  . 

•  NO  VIRTUAL  MEMORY  STORAGE  AVAILABLE.  The  addressable  limit  of 
the  virtual  memory  has  been  reached.  There  is  no  recovery 
other  than  to  reduce  the  virtual  memory  requirements  of  the 
task  being  built  along  the  lines  suggested  earlier. 

The  work  file  normally  resides  on  the  device  from  which  TKB  was 
installed.  You  can  change  the  device  by  reassigning  logical  unit  8 
through  the  Monitor  Console  Routine  or  by  editing  the  build  file  and 
relinking  TKB. 

System  overhead  for  work  file  accesses  is  incurred  in  translating  a 
relative  block  number  in  the  file  to  a  physical  disk  address.  To 
minimize  this  overhead,  TKB  requests  disk  space  in  contiguous 
increments.  The  size  of  each  increment  is  equal  to  the  value  of 
symbol  W$KEXT  defined  in  TKB  build  file.  A  larger  positive  value 
causes  the  file  to  be  extended  in  larger  contiguous  increments  and 
reduces  the  overhead  required  to  gain  access  to  the  file.  The 
increment  should  be  set  to  a  reasonable  value  because  TKB  resorts  to 
noncontiguous  allocation  whenever  contiguous  allocation  fails.  ;  .b 
You  can  reduce  the  size  of  the  work  file  by: 

•  Linking  your  task  to  a  core-resident  library  containing 
commonly  used  routines  (for  example,  FORTRAN  Object  Time 
System)  whenever  possible 
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•  Including  common  modules,  such  as  components  of  an  object  time 
system,  in  the  root  segment  of  an  overlaid  task 

•  Using  an  object  library  or  file  of  concatenated  object  modules 
if  many  modules  are  to  be  linked 

When  you  use  either  of  the  last  two  proc«^dures,  system  overhead  is 
also  significantly  reduced  because  fewer  files  must  be  opened  to 
process  the  same  number  of  modules. 

You  can  reduce  the  number  of  work  file  references  by  eliminating 
unneeded  output  files  and  cross-reference  processing,  or  by  obtaining 
the  short  map.  In  addition,  you  can  usually  exclude  selected  files, 
such  as  the  default  system  object  module  library,  from  the  map.  In 
this  case  you  can  obtain,  and  retain,  a  full  map  at  less  frequent 
intervals . 


P. 1.2   Input  File  Processing 

The  procedures  for  minimizing  the  size  of  the  work  file  and  number  of 
work  file  accesses  also  drastically  reduce  the  amount  of  input  file 
processing . 

A  given  module  can  be  read  up  to  four  times  when  the  task  is  built: 

•  To  build  the  symbol  table 

•  To  produce  the  task  image 

•  To  produce  the  long  map 

•  To  produce  the  global  cross-reference 

Files  that  are  excluded  from  the  long  map  are  read  only  twice.  The 
third  and  fourth  passes  are  eliminated  for  all  modules  when  you 
request  a  short  map  without  a  global  cross  reference. 


F. 1. 3   Summary 

In  summary,  you  can   use   the   following   procedures   to   improve   TKB 
throughput : 

•  Use  the  INSTALL/INC  or  EXTTSK  keyword  to  allocate   more   table 
space. 

•  Increase  maximum  task  size  by  raising   the   system   limit   for 
dyaamic  task  extension. 

•  Reduce  disk  latency  by  placing  the  work  file   on   the   fastest 
random  access  device. 

•  Reduce  system   overhead   by  modifying   the   command   file   to 
allocate  work  file  space  in  larger  contiguous  increments. 

•  Decrease   work   file   size   by    using    resident    libraries, 
concatenated  object  files,  and  object  libraries. 


F-6 


IMPROVING  TASK  BUILDER  PERFORMANCE 


•  Decrease  work  file  size  by  including  common  modules  into  the 
root  segment  of  an  overlaid  task. 

o  Decrease  the  number  of  work  file  references  by  eliminating  the 
map  and  global  cross-reference,  obtaining  the  short  map,  or 
excluding  files  from  the  map. 


F.2   MODIFYING  COMMAND  SWITCH  DEFAULTS 

The  default  switch  settings  and  values  provided  by  the  Task  Builder  as 
released  may  not  suit  the  requirements  of  all  installations.  For 
example,  the  default  /-EA  (no  KEll  Extended  Arithmetic  Element)  would 
be  unsa cisfactory  at  an  installation  that  made  frequent  use  of  this 
hardware . 

You  can  thus  tailor  the  switch  defaults  by  altering  the  contents  of 
the  words  that  contain  initial  switch  states.  Modifying  TKB  in  this 
way  is  a  3-step  process: 

1.  Consult  Tables  F-1  through  F-4  to  determine  the  switch  word 
and  bit  to  be  altered. 

2.  Edit  the  appropriate  TKB  command  file  to  include  the  switch 
word  modification  through  a  GBLPAT  keyword  referring  to  the 
global  switch  word  name. 

3.  Relink  TKB  using  the  modified  command  file. 

The  command  files  for  system  tasks,   as   provided   with   the   released 

system,  require  the  standard  set  of  TKB  defaults;   therefore,  you  must 

retain  and  use  an  unmodified  copy  of  TKB  whenever  such  tasks  are 
rel inked . 

You  use  Tables  F-1  through  F-4  to  alter  the  defaults  as  follows: 

1.  You  identify  the  switch  and  the  file  to  which  it  applies. 

2.  You  consult  tne  switch  category  entry  in  each  tabli?  to  locate 
the  applicable  switch  words. 

3.  You  look  at  the  switch  settings  to  find  the  switch  and 
associated  bit. 

4.  You  specify  the  revised  value  and  switch  word  as  arguments  in 
a  GBLPAT  keyword. 

5.  You  relink  TKB  to  produce  a  version  containing  the 
appropriate  defaults. 

For  exc.iple,  to  change  the  TKB  Extended  Arithmetic  Element  default  to 
/EA,  perform  the  steps  described  below. 

By  consulting  Table  F-1,  you  determine  that  two  switch  words,  $DFSWT 
and  $DFTSK,  contain  task  file  switches.  Of  these,  $DFTSK  contains  the 
default  setting  for  the  /EA  switch  in  bit  13.  Setting  this  bit  to  1 
changes  the  initial  switch  setting  to  /EA.  This  new  value  is  combined 
with  the  initial  contents  to  yield  the  revised  setting  120002.  The 
required  keyword  input  is: 

TKB>GBLPAT=TASKB:$DFTSK: 120002 
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NOTE 

The  setting  of  bit  positions  not   listed 
in  the  tables  must  not  be  altered. 

The  only  switches  that  have  associated  values  are  /AC  and  /PR.  In 
these  cases,  the  value  is  the  number  of  the  initial  APR  used  to  map 
the  task.  You  can  alter  the  default  by  changing  the  value  of  the 
GBLDEF  keyword  for  the  symbol  D$FAPR  in  TKB  build  file.  Only  values  4 
or  5  can  be  used. 


Table  F-1 
Task  File  Switch  Defaults 

Switch  Category:   Task  file 

Switch  Word:   $DFSWT 

Initial  Contents:   0 

Switch  Settings: 

Initial  Initial 

Bit      State  Condition 

15         0        /-XT  Not  abort  after  n  diagnostics 

11         0        /-SQ  Niwt  sequential  PSECT  allocation 

4         0        /-FU  Not  full  overlay  tree  search 
3         0        /RO   Recognize  memory-resident  overlay 

operator . 

2         0        /-ID  Not  user  D-space 

Switch  Category:   Task  file 

Switch  Word:   $DFTSK  >         .  ' 

Initial  Contents:   100002  '      ^ 

Switch  Settings: 

Initial  Initial 

Bit      State  Condition 

15         1        /-CP,  /-AL  Not  checkpointable^ 

14         0        /-FP  Not  Floating  Point  Processor 

13         0        /-EA  Not  Extended  Arithmetic  Element 

1.  The   combination   of   not   checkpointable   with    checkpoint 
allocation  (lOOCOO)  is  illogical  and  should  not  be  use'i. 

(continued  on  next  page) 


F-8 


IMPROVING  TASK  BUILDER  PERFORMANCE 


Table  F-1  (Cont.) 
Task  File  Switch  Defaults 


Switch  Settings:  (Cont.) 


Ini  tial  Initial 

Bit       State  Condition 


12 

0 

11 

0 

10 

0 

9 

0 

8 

0 

7 

0 

6 

0 

5 

0 

4 

0 

2 

0 

1 

1 

0 

0 

/HD   Header 

/-CM  Not  compatibility  mode 

/-DA  No  debugging  aid 

/-PI  Not  position  independent 

/-PR  Not  privileged 

/-TR  No  trace 

/-PM  No  Postmortem  Dump 

/-SL  Not  slave  task 

/SE   Send  to  task  allowed 

/-AC  Not  ancillary  control  processor 

/-AL  No  checkpoint  allocation 

/XH  External  header 


Switch  Category:   Task  File 
Switch  Word:   $DFTSO 
Initial  Contents:   000010 
Switch  Settings: 


Initial  Initial 

Bit       State  Condition 


8         0        /-XH  No  external  header 

3  1         /-SG  RO  and  RW  PSECTs 
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Table  F-2 
Map  File  Switch  Defaults 


Switch  Category:   Map  file 
Switch  Word:   $DFLBS 
Initial  Contents:   120000 
Switch  Settings: 


Initial  Ini  .ial 

Bit      State  Condition 


15         1        /-MA  Do  not  include  system  library  and  STB 

files  in  map 


Switch  Category:   Map  file 
Switch  Word:   $DFMAP 
Initial  Contents:   2040 
Switch  Settings: 


e 


Initial 

Initial 

Bit 

State 

Condition 

10 

1 

/SH   Short  map 

8 

0 

/SP   Spool 

6 

0 

/-CR  No  CREF 

5 

1 

/WI   Wide  format 

Table  F-3 
Symbol  Table  File  Switch  Defaults 


Switch  Category:   Symbol  table  file 
Switch  Word:   $DFSTB 
Initial  Contents:   0 
Switch  Settings: 


Initial  Initial 

Bit      State  Condition 


12         0        /HD  Build  task  with  header 
9         0        /-PI   Task  is  not  position  independent 
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Table  F-4 
Input  File  Switch  Defaults 


Switch  Category:   Input  file 
Switch  Word:   $DFINP 
Initial  Contents:   000100 
Switch  Settings: 


Initial  Initial 

Bit      State  Condition 


15         0        /MA  Include  file  contents  in  map 

6         1        /CC  File  contains  two  or  more  concatenated 

object  modules 

F.3   THE  SLOW  TASK  BUILDER 

TKB.TSK  uses  a  symbol  table  structure  that  can  be  searched  quickly, 
but  which  requires  more  work  file  space  than  that  of  previous 
versions.  You  may  thus  receive  the  following  message  in  some 
instances : 

NO  VIRTUAL  MEMORY  STORAGE  AVAILABLE 

If  this  occurs,  you  should  try  to  reduce  the  work  file  size  by  using 
the  procedures  described  in  Section  F.l.  If  these  procedures  do  not 
sufficiently  reduce  the  work  file  size,  you  can  link  another  version 
of  TKB,  the  Slow  Task  Builder.  This  version  requires  less  storage, 
but  runs  considerably  slower  than  the  other  versions.  The  build  file 
is  STKBLD.CMD,  which  resides  on  the  same  device  and  UFD  as  the  other 
Task  Builder  command  files.  The  default  name  of  STK.TSK,  the  Slow 
Task  Builder,  is  ...TKB.  It  may  be  convenient  to  install  the  Slow 
Task  Builder  with  a  different  name  if  you  want  to  use  both  Task 
Builders  in  your  system. 
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THE  FAST  TASK  BUILDER 

The  Fast  Task  Builder  (FTB)  allows  you  to  build  simple  tasks  about 
four  times  faster  than  the  Task  Builder  (TKB) .  However,  FTB  has 
limited  functionality.  It  can  only  link  single-segment,  nonpr i vi leged 
tasks,  and  supports  a  limited  number  of  switches  and  options. 

The  (FTB)  is  intended  for  use  as  a  load-and-go  type  of  linker.  It 
contains  very  few  options  and  does  not  support: 

•  New  map  format 

•  Overlaid  programs 

•  FORTRAN  virtual  arrays 

•  Production  of  symbol  table  files 

•  Creation  of  resident  libraries 

•  Privileged  tasks 

•  Cluster  libraries 

The  only  supported  switches  are: 

•  /SP  on  map  file   (default  -  /SP) 

•  /CP  on  task  file  (default  =  /CP) ^ 

•  /EA  on  task  file   (default  =  /-EA) 

•  /MM  on  task  file   (default  =  /MM) 

•  /FP  on  task  file   (default  =  /FP) 

•  /DA  on  input  or  task  image  (default  =  /-DA) 

•  /LB  on  an  input  file  in  the  form: 

>TKB  TASK=PROG. OBJ, LIBRARY/LB 
but  not  in  the  form: 

>TBK  TASK=PROG.OBJ,LIBRARy/LB:MODULE 


1.  No  checkpoint  space  is  allocated  in  the  task  image  file, 
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The  supported  option  inputs  are: 

•  ASG   (same  defaults  as  TKB) 

•  STACK   (same  default  as  TKB) 

•  UNITS 

•  TASK  (same  default  as  TKB) 

•  EXTSCT 

•  ACTFIL   (same  default  as  TKB) 

•  MAXBUF   (same  default  as  TKB) 

•  LIBR 

•  COMMON 

•  RESLIB   (same  defaults  as  TKB) 

•  RESCOM   (same  defaults  as  TKB) 

•  SUPLIB 

•  RESSUP   (same  defaults  as  TKB) 

FTB  supports  lin)<ing  to  shared   regions   but   not  building   a   shared 

region.    FTB  cannot  link  to  clustered  libraries.  Though  FTB  can  link 

to  supervisor-mode  libraries,  it  cannot  link  to  overlaid 
supervisor-mode  libraries. 

FTB  allocates  symbol  table  space  from  the  end  of  its  image  to  the   end 

of  the  partition.   It  does  not  have  a  virtual  symbol  table.   An  Extend 

Task  or  equivalent  of  8K  is  recommended.  FTB  does  not  dynamically 
extend  itself  at  run  time. 

FTB  runs  approximately  four  times  faster  than  TKB  on  an  11/70  with 
RP04S  when  TKB  is  running  with  a  totally  resident  symbol  table.  In 
smaller  systems  with  slower  disks,  the  ratio  should  be  much  higher. 

FTB  also  supports  shared  regions, 

FTB  uses  asynchronous  system  traps  (ASTs)  and  therefore  requires  AST 
support  in  the  Executive. 
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The  Task  Builder  (TKB)  produces  diagnostic  and  fatal 
Error  messages  are  printed  in  the  following  forms: 


error   messages. 


TKB  --  *DIAG*-error-m^'ssage 


or 


TKB 


♦FATAL* -error-message 


Some  errors  are 
such   a   rase, 


correctable  when  command  input  is  from  a  terminal.  In 
a  diagnost?  error  message  can  be  printed,  the  error 
corrected,  and  the  task-bui iding  sequence  continued.  However,  if  the 
same  error  is  detected  in  an  indirect  command  file,  a  correction 
cannot  be  made  and  the  Task  Builder  aborts. 

Some  diagnostic  error  messages  merely  advise  you  of  an  unusual 
condition.  If  you  consider  the  condition  normal  for  your  task,  vou 
can  install  and  run  the  task  image. 


NOTE 

The  Task  Builder  exits  with  two 
statuses:  it  returns  an  ERROR  status 
when  it  encounters  a  diagnostic  error, 
and  a  SEVERE  ERROR  when  it  encounters  a 
fatal  error.  (For  more  information 
about  the  Exi t-Wi th-Status  directive, 
see  the  RSX-llM/M-PLUS  Executive 
Reference  Manual . ) 


This  appendix  tabulates  the  error  messages  produced  by  TKB.  Most  of 
the  messages  are  self-explanatory.  In  some  cases,  the  line  in  which 
the  error  occurred  is  printed. 

A  Software  Performance  Report  (SPR)  should  be  submitted  to  DIGITAL  in 
cases  where  the  explanation  accompanying  a  message  refers  to  a  system 
error  . 

Allocation  failure  on  file  file-name 

TKB  could  not  acquire  sufficient  disk  space  to  store  the  task 
image  file,  or  did  not  have  write-access  to  the  UFD  or  volume 
that  was  to  contain  the  file. 
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Blank  P-8«ction  name  is  illegal 
over  1  ay-description- line 

The  overlay-description-line  printed  contains  a  .PSECT  directive 
that  does  not  have  a  p-section  name. 

Cluster  library  element  library-name  does  not  have  noil  root 

This  is  a  fatal  error.  All  libraries,  except  the  first,  must  be 
PLAS-overlaid  and  have  a  null  root.  The  first  library  in  the 
group  can  be  nonoverlaid  or  overlaid  with  a  null  or  non-null 
root . 

Command  I/O  error 

An  I/O  error  occurs  on  a  command  input  device.  (Device  may  not 
be  on  line,  or  possible  hardware  error.) 

Command  syntax  error 

command-line 

The  command-line  printed  has  incorrect  syntax. 

Complex  relocation  error  -  divide  by  zero:   module 

module-name 

A  divisor  having  the  value  0  was  detected  in  a  complex 
expression.  The  result  of  the  divide  was  set  to  0.  (Probable 
cause:   division  by  a  global  symbol  whose  value  is  undefined.) 

Conflicting  base  addresses  in  cluster  library 

This  conflict  arises  when  you  specify  APRs,  for  both  PIC  and 
non-PIC  libraries  that  are  included  in  the  cluster.  See  the  APR 
parameter  as  described  in  the  CLSTR  option.  This  is  a  fatal 
error . 

Disk  image  core  allocation  too  large 

invalid-line 

The  minimum  disk  allocation  specified  in  the  invalid  line  is 
greater  than  128. 

File  file-name  attempted  to  store  data  in  virtual  section 

The  file  contains  a  module  that  has  attempted  to  initialize  a 
virtual  section  with  data. 

File  file-name  has  illegal  format 

The  file  file-name  contains  an  object  module  whose  format  is  not 
valid . 

Illegal  APR  reservation 

An  APR  specified  in  a  COMMON,  LIBR,  RESCOM,  or  RESLIB  keyword  is 
outside  the  range  0-7. 

Illegal  cluster  configuration 

If  the  cluster  contains  a  non-overlaid  library,  tbat  library  must 
be  the  first  library  in  the  c?.uster.  Check  the  >jonf igu-ation  of 
the  libraries  in  the  cluster.   This  is  a  fatal  error. 
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Illegal  default  priority  specified 

optior.-l  ine 

The  option-line  printed  contains  ?  priority  greater  than  250. 

Illegal  device/volume 

inva] id-1 ine 

The  invalid  line  printed  contains  an  illegal  device 
speci  f ication. 

Illegal  directory 

invalid-line 

The  invalid  line  printed  contains  an  illegal  directory  name. 

Illegal  error-severity  code  octal-list 

System  error  (no  recovery).  An  SOR  should  be  submitted  with  a 
copy  of  the  message  containing  the  octal- lii;t  as  printed. 

Illegal  filename 
invalid-1 ine 

The  invalid-line  printed  contains  a  wildcard  (')  in  a  file 
specification.   Using  wildcards  is  prohibited. 

Illegal  get  command  line  error  code 

System  error  (no  recovery) . 

Illegal  logical  unit  number 

inval id-line 

The  invalid-line  printed  contains  a  device  assignment  to  a  unit 
number  larger  than  the  number  of  logical  units  specified  by  the 
UNITS  keyword,  or  assumed  by  default  if  the  UNITS  keyword  is  not 
used . 

Illegal  multiple  parameter  sets 

invalid-line 

The  invalid-line  printed  contains  multiple  sets  of  parameters  tor 
a  keyword  that  allows  only  a  single  parameter  set. 

Illegal  number  of  logical  units 

invalid-line 

The  invalid-line  printed  contains  a  logical  unit  number  greater 
than  250. 

Illegal  ODT  or  task  vector  size 

ODT  or  SST  vector  size  specified  is  greater  than  32  words. 

Illegal  overlay  description  operator 

invalid-line 

The  invalid-line  printed  contains  an  unrecognizable  operator  in 
an  overlay  description.  This  error  occurs  if  the  first  character 
in  a  p-section  or  segment  name  is  a  dot  {.). 
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Illegal  overlay  directive 

inval id-1 ine 

The  invalid-line  printed  cont-.ins  an  unrecognizable  overlay 
di  rect i ve. 

Illegal  partition/common  block  specified 

invalid-1 ine 

User-defined  base  or  length  is  not  on  a  32-word  boundary. 

Illegal  P-section/segment  attribute 
invalid-line 

The  invalid-line  printed  contains  a  program  section  or  segment 
attribute  that  is  not  recognized. 

Illegal  reference  to  library  P-section  p-sect-name 

A  task  has  attempted  to  reference  a  p-sect-name  existing  in  a 
shared  region  but  has  not  named  the  shared  region  in  a  keyword. 
This  error  occurs  when  you  explicitly  specify  an  STB  file  as  an 
input  file,  but  you  have  not  specified  the  library  to  which  the 
STB  file  belongs  in  an  option. 

Illegal  switch 

f i  le-speci  fication 

The  file-specification  printed  contains  an  illegal  switch  or 
switch  value. 

Incompatible  reference  to  library  P-section  p-sect-name 

A  task  has  attempted  to  reference  more  storage  in  a  shared  region 
than  exists  in  the  shared  region  definition. 

Incorrect  library  module  specification 

invalid-1 ine 

The  invalid-line  contains  a  module  name  with  a  non-Radix-50 
character . 

Indirect  command  syntax  error 

inval id-1 ine 

The  invalid-line  printed  contains  a  syntactically  incorrect 
indirect  file  specification. 

Indirect  file  depth  exceeded 
invalid-line 

The  invalid-line  printed  gives  tne  file  reference  that  exceeded 
the  permissible  indirect  file  depth  (2). 

Indirect  file  open  failure 

invalid-line 

The  invalid-line  contains  a  reference  to  a  command  input  file 
that  could  not  be  located. 

Insufficient  APRs  available  to  map  read-only  root 

TKB  could  not  find  enough  free  APRs  to  map  the  read-only  portion 
of  a  multiuser  task. 
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Insufficient  paraneters 

invalid-line 

The  invalid-line  contains  a  keyword  with  an  Insufficient  number 
of  parameters  to  complete  its  meaning. 

Invalid  APR  reservation 

inval id-1 ine 

APR  is  specified  on  a  keyword  for  an  absolute  library. 

Invalid  keyword  identifier 

invalid-line 

The  invalid-line  printed  contains  an  unrecognizable  keyword. 

Invalid  parti tion/conunon  block  specified 
invalid-line 

A  partition  is  invalid  for  one  of  the  foDowing  reasons: 

•  TKB  cannot  find  the  partition  name  in  the  host  system  in  order 
to  get  the  base  and  length. 

e  The  system  is  mapped,  but  the  base  address  of  the  partition  is 
not  on  a  4K  boundary  for  a  nonrunnable  task  or  is  not  0  for  a 
runnable  task. 

•  The  memory  bounds  for  the  partition  overlap  a  shared  region. 

•  The  partition  name  is  identical  to  the  name  of  a  previously 
defined  COMMON  or  LIBR  shared  region. 

•  The  top  address  of  the  partition  for  a  runnable  task  exceeds 
32K  minus  32  words  for  a  mapped  system,  or  exceeds  28K  minus  1 
for  an  unmapped  system. 

•  A  system-controlled  partition  was  specified  for  an  unmapped 
system. 

Invalid  reference  to  mapped  array  by  module  module-name 

The  module  has  attempted  to  initialize  the  mapped  array  with 
data.  An  SPR  should  be  submitted  if  DIGITAL-suppl led  software 
caused  this  problem. 

Invalid  window  block  specification 

inval id- line 

The  number  of  extra  address  windows  specified  exceeds  the  number 
permitted.  On  an  RSX-llM  system,  you  can  specify  as  many  as  7 
extra  window  blocks;  on  an  RSX-llM-PLUS  system,  you  can  specify 
as  many  as  15  extra  window  blocks. 

If  you  build  a  task  on  an  RSX-llM  system  and  specify  more  window 
blocks,  you  get  this  error  message,  but  the  task  will  build. 
However,  it  cannot  be  installed  and  run  on  an  RSX-llM  system. 

I/O  error  library  image  file 

An  I/O  error  has  occurred  during  an  attempt  to  open  or  read  the 
Task  Image  File  of  a  shared  region. 
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I/O  error  on  input  file  file-name 

This  error  occurs  when  TKB  cannot  read  an  input  file 
specification  (for  example,  when  the  command  line  is  greater  than 
80  characters) . 

I/O  error  on  output  file  file-name 

Label  or  name  is  multiple  defined 
inval id-1 ine 

The  invalid-line  printed  defines  a  name  that  has  already  appeared 
as  a  .FCTR,  .NAME,  or  .PSECT  directive. 

Library  file  filename  has  incorrect  format 

A  module  has  been  requested  from  a  library  file  that  has  an  empty 
module  nr-ne    table. 

Library  not  built  as  a  supervisor  node  library 

The  library  referred  to  in  a  RESSUP  or  SUPLIB  option  was  built 
without  a  completion  (CMPRT«X)  routine  and  is  not  a 
supervisor-mode  library. 

Library  library-name  not  found  in  an"  cluster 

All  task  image  and  symbol  table  files  to  be  included  as  cluster 
elements  must  reside  in  LB: [1,1], 

Library  references  overlaid  library 

inval id-1 ine 

An  attempt  was  made  to  link  the  resident  library  being  built  to  a 
shared  region  that  has  memory-resident  overlays. 

Load  addr  out  of  range  in  module  module-n<ime 

An  attempt  has  been  made  to  store  data  in  the  task  image  outside 
the  address  limits  of  the  segment.  This  problem  is  usually 
caused  by  one  of  the  following: 

•  An  attempt  to  initialize  a  p-section   contained   in   a   shared 
region 

•  An  attempt  to  initialize   an   absolute   location   outside   the 
limits  of  the  segment  or  in  the  task  header 

•  A  patch  outside  the  limits  of  the  segment  to  which  it  applies 

•  An  attempt  to  initialize  a  segment  having  the  NODSK  attribute 

Lookup  failure  on  file  file  name 
inval id- line 

The  invalid-line  printed  contains  a  file  name  that  cannot  be 
located  in  the  directory. 

Lookup  failure  on  system  library  file 

TKB  cannot  find  the  system  Library  (SYO: [1, 1] SYSLIB.OLB)  file  to 
resolve  undefined  symbols. 
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Lookup  failure  resident  library  file  -  f  i  lenatne.ext 

No  symbol  table  or  task  image  file  can  be  found  for  the  shared 
region  "f i lename .ext . "  If  the  shared  region  was  linked  to  another 
shared  region,  ensure  that  the  task  image  of  both  regions  and  the 
symbol  table  files  exist  on  the  same  device  and  in  the  same  UIC 
as  the  UIC  referenced  by  the  option  RESLIB,  RESCOM,  LIBR,  COMMON, 
RESSUP,  or  SUPLIB. 

Module  module-name  ambiguously  defines  P-section  p-sect-naroe 

The  p-section  p-sect-name  has  been  defined  in  two  modules  not  on 
a  common  path,  and  referenced  from  a  segment  that  is  common  to 
both  paths. 

Module  module-name  ambiguously  defines  symbol  sym-name 

Module  module-name  references  or  defines  a  symbol  sym-name  whose 
definition  exists  on  two  different  paths,  but  is  referenced  from 
a  segment  that  is  common  to  both  paths. 

Module  nodule-name  contains  incompatible  autoload  vectors 

You  ate  trying  to  build  an  I-  and  D-space  task  and  link  it  to  an 
older  existing  library  that  contains  an  old-style  vector  format. 
Rebuild  the  library  with  the  RSX-llM-PLUS  Version  2.1  or  later 
version  Task  Builder  to  create  new-style  vectors  for  the  library. 
Then  rebuild  your  task. 

Module  module-name  illegally  defines  xfr  address  p-sect-name  addr 

This  message  occurs  under  any  one  of  the  following  conditions: 

•  The  start  address  printed  is  odd. 

•  The  module  module-name  is  in  an  overlay  segment  and  has  a 
start  address.  The  start  address  must  be  in  the  root  segment 
of  the  main  tree. 

•  The  address  is  in  a  p-section  that  has  not  yet  been  defined. 
An  SPR  should  be  submitted  DIGITAL-suppl ied  software  caused 
this  problem. 

Module  module-name  multiply  defines  P-section  p-sect-name 

•  The  p-section  p-sect-name  has  been  defined  more  than  once  in 
the  same  segment  with  different  attributes. 

•  A  global  p-section  has  been  defined  more  than  once  with 
different  attributes  in  more  than  one  segment  along  a  common 
path . 

Module  module-name  multiply  defines  symbol  sym-name 

Two  definitions  for  the  relocatable  symbol  sym-name  have  occurred 
on  a  comir.on  path.  Or  two  definitions  for  an  absolute  symbol  with 
the  same  name  but  different  values  have  occurred. 

Module  module-name  multiply  defines  xfr  addr  in  seg 
segment-name 

This  error  occurs  when  more  than  one  module  making  up  the  root 
has  a  start  address. 
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Module  module-name  not  in  library 

TKB  could  not  find  the  module  named   on   the   LB   switch   in   the 
1 ibrary . 

No  dynamic  storage  available 

TKB  needs  additional  symbol  table  storage  and  cannot   obtain   it. 
(If  possible,  install  TKB  in  a  larger  partition.) 

No  memory  available  for  library  library-name 

TKB  could  not  find  enough  free  virtual  memory  to  map  the 
specified  shared  region. 

No  root  segment  specified 

The  overlay  description  did  not  contain  a  .ROOT  directive. 
No  virtual  memory  storage  available 

Maximum  permissible  size  of  the  work  file  is  exceeded.  The  user 
should  consult  Appendix  F  for  suggestions  on  reducing  the  size  of 
the  work  file. 

Open  failure  on  file  file-name 

Option  syntax  error 

i  nval id-1 ine 

The  invalid-line  printed  contains  unrecognizable  syntax. 

Overlay  directive  has  no  operands 

inval id-1 ine 

All  overlay  directives  except  .END  require  operands. 

Overlay  directive  syntax  error 

inval id-1 ine 

The  invalid-line  printed  contains  a  syntax  error  or  references  a 
line  that  contains  an  error. 

Partition  partition-name  has  illeg=^l  memory  limits 

•  The  partition-name  defined  in  the  host  system  has  a  base 
address  alignment  that  is  not  compatible  with  the  target 
system. 

•  The  user  has  attempted  to  build  a  privileged  task  in  a 
partition  whose  length  exceeds  the  task's  available  address 
space  {8K  or  12K) . 

Pass  control  stack  overflow  at  segment  segment-name 

System  error.  An  SFk  should  be  submitted  with  a  copy  of  the  ODL 
file  associated  with  the  error. 

PIC  libraries  may  not  reference  other  libraries 

invalid-line 

The  user  has  attempted  to  build  a  position-independent  shared 
region  that  references  another  shared  region. 
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P-section  p-sect-name  has  overflowed 

A  section  greater  than  32K  has  been  created. 
Required  input  file  missing 

At  least  one  input  file  is  required  for  a  task  build. 

Required  partition  not  specified 

The  PAR  keyword  was  not  used  when  running  TKB  on  an  RSX-llD  host 
system.  The  keyword  must  contain  explicit  base  address  and 
length  specifications. 

Resident  library  has  incorrect  address  alignment 

invalid-line 

The  invalid-line  specifies  a  shared  region  that  has  one  of  the 
following  problems: 

•  The  library  references  another  library   with   invalid   address 
bounds  (that  is,  not  on  4K  boundary  in  a  mapped  system). 

•  The  library  has  invalid  address  bounds. 

Resident  library  mapped  array  allocation  too  large 
inval id-line 

The  invalid-line  printed  contains  a  reference  to  a  shared  reg'on 
that  has  allocated  too  mucn  memory  in  the  task's  mapped  array 
area.   The  total  allocation  exceeds  2.2  million  bytes. 

Resident  library  memory  allocation  conflict 
keyword-string 

One  of  the  following  problems  has  occurred: 

•  More  than  seven  shared  regions  have  been  specified. 

•  A  shared  region  has  been  specified  more  than  once. 

•  Non-position-independent    shared    regions    whose    memory 
allocations  overlap  have  been  specified. 

Root  segment  is  multiply  defined 

inval id-line 

The  invalid-line  printed  contains  the  second  .ROOT  directive 
encountered.   Only  one  .ROOT  directive  is  allowed. 

Segment  seg-name  has  addr  overflow:   allocation  deleted 

Within  a  segment,  the  program  has  attempted  to  allocate  more  than 
32,764  words  (32K-1  words;.  A  map  file  is  produced,  but  no  task 
image  file  is  produced. 

Segment  seg-name  not  found  for  patch 

The  Task  Builder  could  not  locate  the  named  segment  for  d  global 
patch.   The  option  used  was  GBLPAT=X: Y: 0. 
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Sap«rvisoiL'  nod*  conpletlon  routine  is  un>1«fln«d 

TKB  could  not  locate  the  symbol  X,  which  was  specified  in  the 
CMPRT-X  option. 

Symbol  sym-name  not  found  for  patch 

TKB  could  not  locate  symbol  Y  foV  a  global  patch.  The  option 
used  was  GBLPAT=«X:  Y  :  0. 

Task  has  illegal  memory  limits 

An  attempt  has  been  made  to  build  a  task  whose  size  exceeds  the 
partition  boundary.  If  a  task  image  file  was  produced,  it  should 
be  deleted. 

Task  has  illegal  physical  memory  limits 
tr  ipped-array   task-image    task  extension 

The  sum  of  the  parameters  displayed  —  mapped  array  size,  task 
image  size,  and  task  extension  --  exceeds  2.2  million  bytes.  The 
quantities  are  shown  as  octal  numbers  in  units  of  64-byte  blocks. 
Any  resulting  task  image  file  should  be  deleted. 

Task  image  file  filename  is  noncontiguous 

Insufficient  contiguous  disk  space  was  available  to  contain  the 
task  image.  A  noncontiguous  file  was  created.  After  del  ting 
unnecessary  files,  the  /CO  switch  in  PIP  should  be  used  to  create 
a  contiguous  copy, 

Ta?k  requires  too  many  window  blocks 

The  number  of  address  windows  required  by  the  task  and  any  shared 
regions  exceeds  8  for  RSX-llM  tasks  and  16  for  RSX-llM-PLUS 
tasks . 

Task-build  aborted  via  request 
option-1 ine 

The  option-line  contains  a  request  from  the  user  to  abort  the 
task  build. 

Too  many  nested  .ROOT/.FCTR  directives 

inval id-1 ine 

The  invalid-line  printed  contains  a  .FCTR  directive  that  exceeds 
the  maximum  nesting  level  (16). 

Too  many  parameters 
inval id-1 ine 

The  invalid-line  printed  contains  a  keyword  with  more  parameters 
than  required. 

Too  many  parentheses  levels 
invalid-1 ine 

The  invalid-line  printed  contains  a  parenthesis  that  exceeds  the 
maximum  nesting  level  (16), 
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Truncation  error  In  nodule  module-name 

An  attempt  has  been  made  to  load  a  global  value  greater  than  +127 
or  less  than  -128  into  a  byte.  The  low-order  eight  bits  are 
loaded . 

Unable  to  open  work  file 

The  work  file  device  is  not  mounted.  (The  work  file  is  usually 
located  on  the  same  device  as  is  the  Task  Builder.) 

Dnbalanced  parentheses 
invalid-line 

The  invalid-line  printed  contains  unbalanced  parentheses. 
n  Undefined  symbols  segment  seg-name 

The  segment  named  contains  n  undefined  symbols.  If  no  memory 
allocation  file  is  requested,  the  symbols  are  printed  on  the 
terminal . 

Virtual  section  has  illegal  address  limits 

option-line 

The  option-line  printed  contains  a  VSECT  keyword  whose  base 
address  plus  window  size  exceeds  177777. 

Work  file  I/O  error 

An  I/O  error  occurs  during  an  attempt  to  reference  data  stored  by 
TKB  in  its  work  file. 
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ABSOLUTE  SHARED  REGION 

A  shared  region  that  has  che  same  virtual  addresses  in  all  tasks 
that  refer  to  it. 

AUTOLOAD 

The  method  of  loading  overlay  segments,  in  which  the  Overlay 
Run-Time  routines  automatically  load  overlay  segments  when  they 
are  needed  and  handles  any  unsuccessful  load  requests. 

AUTOLOAD  VECTOR 

A  transfer  of  control  instruction  generated  by  the  Task  Builder 
to  resolve  an  up-tree  reference  to  a  global  symbol. 

CO-TREE 

One  of  one  or  more  secondary  tree  structures  within  a  multiple 
tree  overlay  structure.  When  a  co-tree's  root  segment  contains 
code  or  data,  the  root  segment  of  the  co-tree  is  made  resident  in 
physical  memory  through  calls  to  the  Overlay  Run-Time  routines. 

COMMON  BLOCK 

Another  name  for  resident  common. 
DISK-RESIDENT 

That  which  resides  on  disk  storage  until  needed. 

DISK-RESIDENT  OVERLAY  SEGMENT 

An  overlay  segment  that  shares  the  same  physical  memory  and 
virtual  address  space  with  other  segments.  The  segment  is  read 
in  from  disk  each  time  it  is  loaded  (compare  Memory-Resident 
Overlay  Segment)  . 

GLOBAL  CROSS-REFERENCE 

A  list  of  global  symbols,  in  alphabetical  order,  accompanied  by 
the  name  of  each  referencing  module. 

GLOBAL  SYMBOL 

A  symbol  whose  definition  is  known  outside  the  defining  module. 

HEADER 

That  portion  of  a  task  image  that  contains  the  task's 
characteristics  and  status.  Shared  regions,  although  built  like 
a  task,  do  not  have  a  header. 
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HOST  SYSTEM 

The  system  on  which  a  task  is  built. 
LOGICAL  ADDRESSES 

The  actual  physical  addresses  that  the  task  can  access. 
LOGICAL  ADDRESS  SPACE 

The  total  amount  of  physical  memory  to  which  the  task  has  access 
rights . 

MAIN  TREE 

An  overlay  tree  whose  root  segment  is  loaded  by  the  Executive 
when  the  task  is  made  active. 

MANUAL  LOAD 

The  method  of  loading  overlay  segments  in  which  the  user  includes 
explicit  calls  in  his  routines  to  load  overlays  and  handles 
unsuccessful  load  requests. 

MAPPED  ARRAY  AREA 

An  area  of  the  task's  physical  memory,  preceding  the  task  imige, 
that  is  used  for  storage  of  large  arrays.  Space  in  the  area  is 
reserved  by  means  of  the  VSECT  keyword  or  through  a  Mapped  Array 
Declaration  contained  in  an  object  module.  Access  is  through  the 
mapping  directives  issued  at  run  time. 

MEMORY  ALLOCATION  FILE 

The  output  file  created  by  the  Task  Builder  that  lists 
information  about  the  size  and  location  of  components  within  a 
task  . 

MEMORY-RESIDENT 

In  general,  that  which  resides  in  memory  all  the  time.  The 
entity,  as  in  the  case  of  memory-resident  overlays,  may  initially 
reside  on  disk. 

MEMORY-RESIDENT  OVERLAY  SEGMENT 

An  overlay  segment  that  shares  virtual  address  space  with  other 
segments,  but  which  resides  in  its  own  physical  memory.  The 
segment  is  loaded  from  disk  only  the  first  time  it  is  referenced; 
thereafter,  mapping  directives  are  issued  in  place  of  disk  load 
requests . 

OVERLAY  DESCRIPTION  LANGUAGE 

A  language  that  allows  you  to  describe  the  overlay  structure  of  a 
task . 
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OVERLAY  RUNTIME  ROUTINES 

A  set  of  system  library  subroutines  linked  as  part  of  an  overlaid 
task  that  are  called  to  load  segments  into  memory. 

OVERLAY  SEGMENT 

A  segment  that  shares  virtual  address  space  with  other  segments, 
and  is  loaded  when  needed. 

OVERLAY  TREE 

A  tree  structure  consisting  of  a  root  segment  and  optionally  one 
or  more  overlay  segments. 

PATH 

A  route  that  is  traced  from  one  segment  in  the  overlay  tree  to 
another  segment  in  that  tree. 

PATH-DOWN 

A  path  toward  the  root  of  the  tree. 

PATH-LOADING 

The  technique  used  by  the  autoload  method  to  load  all  segments  on 
the  path  between  a  calling  segment  and  a  called  segment. 

PATH-UP 

A  path  away  from  the  root  of  the  tree. 

PHYSICAL  ADDRESS 

The  assigned  byte  location  in  physical  memory,  which  is  usually 
located  in  the  processing  unit. 

POSITION-INDEPENDENT  REGION 

A  shared  region  that  can  be  placed  anywhere  in  a  referencing 
task's  virtual  address  space  when  the  system  on  which  the  task 
runs  has  memory  management  hardware. 

PRIVILEGED  TASK 

A  task  that  has  privileged  memory  access  rights.  A  privileged 
task  can  access  the  Executive  and  the  I/O  page  in  addition  to  Its 
own  partition  and  referenced  shared  regions. 

PROGRAM  SECTION 

A  section  of  memory  that  is  a  unit  of  the  total  allocation.  A 
source  program  is  translated  into  object  modules  that  consist  of 
program  sections  with  attributes  describing  access,  allocation, 
relocatabil i ty ,  and  so  forth. 


REGION 


A  contiguous  block  of  physical  addresses  in   which   a   driver,   a 
task,  a  resident  common,  or  library  resides. 
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RESIDENT  COMMON 

A  shared  region  in  which  data  resides  that  can  be  shared  by  two 
or  more  tasks. 

RESIDENT  LIBRARY 

A  shared  region  in  which  single  copies  of  commonly  used 
subroutines  reside  that  can  be  shared  by  two  or  more  tanks. 

ROOT  SEGMENT 

The  segment  of  an  overlay  tree  that,  once  loaded,  remains  in 
memory  dur     the  execution  of  the  task. 

RUNNABLE  TASK 

A  task  that  has  a  header  and  stack  and  that  can  be  installed  and 
executed . 

SHARED  REGION 

A  shared  region  is  a  block  of  data  or  code  that  resides  in 
physical  memory  and  can  be  used  by  any  number  of  tasks.  A  shared 
region  is  built  and  installed  separately  from  the  task. 

SUPERVISOR-MODE  LIBRARY 

A  library  of  routines  that  uses  the  supervisor-mode  memory 
management  APRS  to  map  to  both  the  task  and  its  own  routines. 

SYMBOL  DEFINITION  FILE 

The  output  object  file  created  by  the  Task  Builder  that  contains 
the  global  symbol  definitions  and  values  and  sometimes  program 
section  names,  attributes,  and  allocations  in  a  format  suitable 
for  reprocessing  by  the  Task  Builder.  Symbol  definition  files 
contain  linkage  information  about  snared  regions. 

TARGET  SYSTEM 

The  system  on  which  a  task  executes. 

TASK  IMAGE  FILE 

The  output  file  created  by  the  Task  Builder  that  contains  the 
executable  portion  of  the  task. 

VIRTUAL  ADDRESSES 

The  addresses  within  the  task.  Task  addresses  can  range  from 
zero  through  177777(8)  depending  on  the  length  of  the  task. 

VIRTUAL  ADDRESS  SPACE 

That  space  encompassed  by  the  range  of  virtual  addresses  that  the 
task  uses, 

VIRTUAL  PROGRAM  SECTION 

A  program  section  that  has  virtual  memory  allocated  to  it,  but 
not  physical  memory.  Virtual  address  space  is  mapped  into 
physical  memory  at  run-time  by  means  of  the  mapping  ditectives. 
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WINDOW 


A  continuous  virtual  address  space  that  can  be  moved  to  allow  tho 
task  to  examine  different  parts  of  a  region  or  different  regions. 


WINDOW  BLOCK 


A  structure  defined  by  the  Task  Builder  that  describes  a  range  of 
continuous  virtual  addresses. 
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Abort 
TKB 

during  input,  11-4 
ABORT  option,  11-4 
Absolute  region 

See  Region 
ABSPAT  option,  11-5 
/AC  switch,  10-5 
Access-code,  2-4  to  2-5 

grouping  program  section  by, 
10-36 
ACP 

specifying  APR,  lO-'j 
specifying  task  as,  10-5 
ACTFIL  option,  li-G 
Active  Page  Register 

See  APR 
Address 

assigning,  2-1 
concepts,  2-13 
logical,  2-14 
mapped  system,  2-18 
physical,  2-13 

mapped  system,  2-17 
space,  2-14 
virtual,  2-14 
virtual  and  logical 

coincidence,  2-15 
space  translation,  2-23 
transfer,  A-5 
virtual,  2-13 

mapped  system,  2-17  to  2-18 
virtual  and  logical 

relationship,  2-17,  2-21 
virtual  space 

co-tree  and  main  tree,  3-40 
disk-resident  overlay,  3-1 

to  3-4 
division,  2-18 
division  by  memory 

management,  2-18 
in  overlay  tree,  3-24 
memory-resident  overlay, 

3-6 
overlaid  task,  3-10,  3-14 
overlay,  3-5,  3-33  to  3-35 
reducing  usage  of,  3-1 
virtual  space  allocation 
diagram 
creating  ODL  file,  3-36 
virtual  space  and  memory 

overlaid  task,  3-11  to  3-14 
/AL  switch,  10-6 
$$ALER 

reserved  PSECT  name,  E-2 


ALERR  module,  5-53 
Allocation-code,  2-4  to  2-5 
ALSCT  FORTRAN  s  ^routine,  5-56 

to  5-58 
$$ALVC 

PSECT,  7-11 

reserved  PSECT  name,  E-2 
$$ALVD 

PSECT,  7-11 

reserved  F'SECT  name,  E-2 

$yAi,vi 

PSECT,  7-il 

reserved  PSECT  name,  E-2 
Ancillary  control  processor 

See  ACP 
APR,  2-16 

I-  and  D-space 

allocation  in  multiuser 
task,  9-3 
relocatable  region 

specifying  for,  5-6 
resident  common 

system-owned,  11-11 
resident  library 

system-owned,  11-11 
specifying  for  ACP,  10-5 
supervisor-mode,  8-2  to  8-3 
Arithmetic  element 
extended 

specifying,  10-16 
Array  declaration 

mapped,  A-10 
ASG  option,  11-7 
Asterisk  (*) 

See  also  Autoload  indicator 
cross-reference 

of  overlaid  task,  4-13 
cross-reference  listinq, 
10-12 
At  sign  (@) 

cross-reference 

of  overlaid  task,  4-13 
cross-reference  listing, 

10-12  to  10-13 
indirect  file,  1-5 
Attribute 

in  .NAME  directive 
DSK,  3-28 
GBL,  3-28 
NODSK,  3-28 
NOGBL,  3-28 
program  section 

restriction,  2-3 
save,  2-4 
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$$AUTO 

PSECT,  5-52  to  5-53 
reserved  PSECT  name,  E-2 
AUTO  module,  5-52 
AUTOL  module,  5-52 
Autoload,  4-1 

applying  indicator 

co-tree  root,  4-2 

.FCTR  label  name,  4-3 

file  name,  4-2 

portions  of  ODL  tree,  4- 

program  section  name,  4- 

segment  name,  4-3 
code  sequence 

conventional  task,  4-5 
error  handling,  4-11  to  4- 
indicator,  4-2 

efficiently  placed,  4-6 
overhead  in  region,  5-13 
path  loading,  4-3  to  4-4 
specifying,  4-1 
vector,  4-4 

eliminating  unnecessary, 
4-6 

I-  and  D-space,  7-9,  7-11 

overlay,  3-20 
vector  format 

conventional  task,  4-4 

I-  and  D-space,  4-4  to  4-5 
Autoloadable 

data  segment,  4-7 
making  file 

using  file  name,  4-2 
making  program  section,  4--3 

.BLK 

See  Program  section 
Block 

label,  2-8 
Buffer  record 

maximum  size,  11-23 
Build  file 

modi  f ying 

to  improve  performance,  F-1, 
F-5 

/CC  switch,  10-7 
Checkpoint 
area 

in  task  image,  B-9 
space 

allocating,  10-6,  10-10 
Checkpointable  task 

specifying  a,  10-6,  10-10 
Circumflex  () 

cross-reference  listing, 

10-12  to  10-13 
global  cross-reference 

of  an  overlaid  task,  4-13 
CLSTR  option,  11-8  to  11-9 
Cluster  library,  5-44 

See  also  Library 
/CM  switch,  10-8 


8-9 

rout  i 
8-9 
8-9, 

libra 


to  2 

2-4 

2-4 

2-7 
2-7 


$CMPAL 

completion 
8-9 
CMPAL  option, 
$CMPCS 

completion 
CMPCS  module, 
CMPRT  option, 
use  in  CSM 
use  in  supervise 
library,  8-7 
/CO  switch,  10-9 
Code 

access,  2-4 
al location, 
relocation , 
scope,  2-4, 
type,  2-5, 
Comma  {  , ) 

See  ODL  operator 
Command 
file 

indirect,  1-5 
interaction  wi 
1-5  to  1-6 
level  of  indir 
with  ODL,  3-30 
line 

comments  in,  1 
form,  1-2 
multi-line  inp 
option  input, 
output  file  in 

1-3 

terminating    ch 

1-5    to   1-6 

to   build   a    tas 

UFD  convention 

sequence 

comments  in,  1 
simple,  1-2 
Comment 

in  command  seque 
in  line,  1-8 
Common,  5-1 ,  5-26 
See  also  Region 
allocation  diagr 
assigning  refere 
building  a  linki 

to  5-22 

building  and  lin 

5-17  to  5-18 

building  and  lin 

device,  5-26 

device,  5-26  to  5 

See  also  Devic 

establishing  off 

in  MACRO-11 

building  and  1 
5-17  to  5- 
building  and  1 
See  Region 


routine,  8-8  to 


ne,  8-8 

11-10 
ry,  8-3,  8-8 
r-mode 


-5 

to  2-5 


th  indirect, 
ection,  1-7 

-8 

ut,  1-3 

1-3 

terpretation , 

aracter,    1-3, 

k,    1-2 
,    1-9 

-8 


nee,    1-8 

to   5-31 

am,    5-20 
nces,    5-23 
ng    task,    5-21 

king    to,    5-14, 

k  i  ng    to    a 

to    5-31 
-31 

e   common 
set    in,    5-28 

inking    to, 
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Common  (Cent.) 

installing  in  RSX-llM,  5-2  to 

5-3,  5-20 
installing  in  RSX-llM-PLUS, 

5-2  to  5-3,  5-20 
linking  to  region,  5-14 
map,  5-19 
PSECT 

building  a  linking  task, 
5-23 
region,  2-19 
resident,  5-1  to  5-2 

declaring,  11-11,  11-28 
name  block  data,  B-8 
specifying  a,  10-9 
typical,  5-2 
COMMON  option,  11-11  to  11-12 
Completion  routine 

$CMPAL,  8-2,  8-8  to  8-9,  8-18 

$CMPCS,  8-2,  8-8 

content  of  a,  8-12  to  8-14 

CSM  library,  8-13 

definition,  A- 11 

identification,  A-11 

name,  A-11 

supervisor-mode  library,  8-2, 

8-7 
user-written,  8-21 
Complex  relocation,  A-22 
entry,  A-23 
operation  codes,  A-22 
Concatenated  object  module 

using  to  reduce  overhead,  F-4 
Control  section 
name,  a-5 
name  entry,  A-5 
Cotree,  3-31 
and  main  tree 

virtual  address  space,  3-40 
global  symbol  resolution, 

3-17 
null  root,  3-31 
ODL  statement 

from  allocation  diagram, 
3-39  to  3-40 
overlay,  3-34  to  3-35 
segment 

affecting  symbol  search  on, 
10-19 
segment  loading,  4-2 
Counter 
location 

definition,  A- 17 
modification,  A-18 
/CP  switch,  10-10 
/CR  switch,  10-11  to  10-13 
Cross-reference 
global 

of  overlaid  task,  4-12  to 
4-14 
listing 

specifying  a,  10-11 


CSM  library 

completion  routine,  8-12  to 

8-14 
dispatching,  8-19 
linking  task 

example  of,  8-9 
supervisor-mode,  8-7 
building,  8-7  to  8-8 
.STB  file,  8-8 
CTRL/Z 

effect  on  Task  Builder,  11-4 

/DA  switch,  10-14 
Data 

adjacency  In  memory,  2-28 
segment 

autoloadable ,  4-7 
structure 

building  a,  2-1 
overlay  of  a,  3-19 
Data  base 

overlay,  B-15 

I-  and  D-space  task,  B-16 
Data  format 
input 

Task  Builder,  A-1 
$$DBTS 

reserved  PSECT  name,  E-2 
Debugging  aid 

Including  a,  10-14 
Declaration  flag  byte 

symbol,  A-7 
Default  of  switch 

modifying,  F-7  to  F-11 
Descriptor 
region,  B-21 
segment,  B-18 
window,  B-20  to  B-21 
Development  step 

program,  1-1 
Dev  ice 

assignment,  11-7 
common,  5-29 

building  and  linking  to  a, 
5-26  to  5-31 
$$DF"T 

reserved  PSECT  name,  E-2 
Dl  rectlve 

memory  management 

In  mapping,  2-24 
.NAME,  3-27 

attributes  for,  3-28 
example  of  use,  3-28 
ODL,  3-23  to  3-24 
.END,  3-23 
.FCTR,  3-25 
introduction,  3-23 
.ROOT,  3-23 
•PSECT,  3-29 

use  of  parentheses,  3-24 
Directory  record 

declare  global  symbol,  A-2 
end  of  global  symbol,  A-11 
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Directory 
global 

end  o 
Interna 
relocat 

Disk  imag 
convent 

Disk-resi 

overlay 

load! 

overlay 

Di  splaced 
interna 

/DL  switc 

DSPPAT  op 

Dump 

See  Pos 
See  Sna 
memory. 

Dynamic  r 
5-43 


record  (Cont.) 
symbol 
f,  A-11 

1  symbol,  A-24 
ion,  A-12 
e,  2-8  to  2-9 
ional  task,  7-6 
dent 

,  3-1  to  3-2 
ng,  4-1 

structure,  3-2 

relocation 
1,  A-15 
h,  10-15 
tion,  11-13 

tmortem  dump 
pshot  dump 

D-1 
egion,  2-20,  5-40 


to 


/EA  switch, 
/EL  switch. 
Element 
extended 
speci  f y 
.END  direct 
End  of  glob 

A-U 
End  of  modu 
Error 

exit  TKB 
handl ing 
$ALERR 
for  aut 
for  man 
overlay 
message 
Exclamation 
See  ODL  o 
operator 
See  ODL 
Extend  Task 
to  improv 
EXTSCT  opti 
EXTTSK  opti 


10-16 
10-17 

ar  ithmet ic 

i  ng ,  10-16 

ive,  3-23 

al  symbol  directory, 

le  record,  A-24 

commands  on,  11-4 

entry,  4-12 

oload,  4-11  to  4-12 

ual  load,  4-12 

,  4-12 

H-1 

po  i  n  t  (  I ) 
perator 

operator 

directive 
e  performance,  F-2 
or,  11-14 
on,  11-15 


Factor 

autoloadable 

making  first  component  of, 
4-3 
Fast  Task  Builder,  G-1 
speed  of,  G-2 
supported 

features,  G-1  to  G-2 
options,  G-2 
switches,  G-1 
unsupported  features,  G-1  to 
G-2 
.FCTR  directive,  3-25 
argument 

library  modules,  3-26 


.FCTR  directive 
argument  (Cont.) 

library  to  resolve 

references,  3-26 
named  input  file,  3-25 
PSECT  name,  3-26 
segment  name,  3-26 
arguments  for,  3-25 
use  of  label  in,  3-25 
.FCTR  statement 

allocation  diagram 

creating  from,  3-38  to  3-39 
File 

command 

level  of  Indirection,  1-7 
declaring  number  of  active, 

11-6 
Indirect  command,  1-5 
Input 

designating  as  debugging 

aid,  10-14 
designating  as  library  file, 

10-23 
directing  selective  symbol 
search,  10-47  to  10-49 
including  content  of  in  map, 

10-26 
processing  to  reduce 

overhead,  F-6 
specifying  as  default 
library,  10-15 
1 Ibrary 

declaring  a,  10-23 
making  file  autoloadable 

using  name,  4-2 
map 

printing,  1-2 
omitting  a  specific  output, 

1-3 
open  at  one  time,  11-6 
sped  f  icatlon 

convention  for,  1-8 
default  for,  1-8 
Floating  Point  Processor 

specifying,  10-18 
FMTBUF  option,  11-16 
FORTRAN 

common  block 

in  overlays,  3-19 
manual  load  calling  sequence, 
4-9  to  4-10 
for  I-  and  D-space  task, 
4-11 
run-time  support 

virtual  program  section, 
5-56  to  5-57 
/FP  switch,  10-18 
$$FSR1 

reserved  PSECT  name,  E-3 
.FSRPT 

low-memory  context,  B-10 
reserved  global  symbol,  E-1 


Index-4 


INDEX 


FTB  library 

overlaid  region, 
/FU  switch,  10-19 


5-13 


GBLDEF  option,  11-17 

GBLINC  option,  11-18 

GBLPAT  option,  11-19 

GBLREF  option,  11-20 

GBLXCL  option,  11-21 

use  in  CSM  library,  8 

-3,  8-7 

to  8-8,  8-18 

Global 

additive  relocation. 

A-16 

relocation.  A- 15 

additive  displaced. 

A-17 

displaced,  A-16 

symbol 

address  of  ODT  SST 

routi  ne , 

11-24 

ambiguously  defined 

in 

overlay,  3-16 

declaration  directory 

record,  A-2 

directory  record  fc 

rmat , 

A-4 

end  of  directory  record. 

A-11 

from  the  default  library. 

3-18 

in  autoloadable  seg 

ment , 

4-4,  4-6 

in  cross-reference 

listing , 

10-12  to  10-13 

multiplydef ined ,  3- 

16 

multisegment  task. 

3-16 

name,  A-6 

name  entry,  A-6 

overlay  search  sequence. 

3-17 

resolution,  2-7 

search  sequence  in 

overlays 

3-16 

undefined,  2-7 

symbol  resolution 

co-tree,  3-17 

default  library,  3- 

18 

in  multisegment  task,  3-16 

/HD  switch,  10-20 
Header,  2-8 

excluding    task,    10-20 
I-   and    D-space    task,    7-11 
in    task    image,    B-10 
task 

fixed    part,    B-11 
variable   part,    B-12 
vector    extension   area, 
High-level    language 

overlay   program    in,    3-40 
3-41 
Host    system,    C-1 

building    a   task    for   another 
system,    C-1 


B-13 


to 


Host    system    (Cont.) 

transferring    from    task,    C-1 
Hyphen    (-) 

See    ODL   operator 

I-    and    D-space 

specifying,    10-21 
I-    and    D-space    task 

See  Task 
1/0  page 

specifying,  10-22 
/ID  switch,  10-21 
Image 

disk,  2-8  to  2-9 

memory,  2-8  to  2-9 
Indirect  command  file,  1-5, 
3-30 

with  ODL,  3-30 
Information  record 

text,  A-11 
Input 

data  format 

Task  Builder,  A-1 

mul ti- 1 ine 

to  the  Task  Builder,  1-3 
Internal  displaced  relocation, 

A- 15 
Internal  symbol 

directory  record,  A-24 

name  entry,  A-5 
$$I0B1 

reserved  PSECT  name,  E-3 
$$I0B2 

reserved  PSECT  name,  E-3 
/IP  switch,  10-22 

Label    block,    2-8 

group,    B-1 
Language 
high-level 

overlay  program  in,  3-40 
/LB  switch,  10-23  to  10-24 
LBLDF$  macro,  B-1 
/LI  switch,  10-25 
LIBR 

linking  to  region,  5-14 
option,  11-11  to  11-12 
Library 

building  a,  5-14 
cluster  ,  5-44 

building,  5-44,  5-48  to 

5-51 
building  exampis   5-48  to 

5-51 
building  rule  1:  overlays, 

5-45 
building  rule  2:  references, 

5-46 
building  rule  3:  .STB  file, 

5-47 
building  rule  4:  stack, 

5-47 
building  rule  5:  PIC,  5-47 
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Library 

cluster  (Cont.) 
building  rule  6 

5-47 
building  rule  summary 
examples,  5-47 
overlay  run-time  supp 

5-51  to  5-53 
resolving  interlibrar 
references,  5-49 
declaring  c ,  10-23 
default 

controlling  symbol  se 

10-15,  10-19 
global  symbol  resolut 
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inhibiting  spooling  of  a, 

10-45 
printing,  1-2 
specifying,  10-26 
including  SYSLIB  contribution, 

10-26 
multiuser  task,  9-7 
overlaid  I-  and  D-space  task, 
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using  Indirect  file  with, 
3-30 
ODL  file 
creating 

start  of  procedure,  3-36 
with  allocation  diagram, 
3-35  to  3-36 
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linking  to  region,  5-14 
separation  of  argument  list, 

1-4  to  1-5 
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CMPRT,  11-10 
COMMON  or  LIBR,  11-11  to 
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GBLREF,  11-20 
GBLXCL,  11-21 
MAXBUF,  11-23 
ODTV,  11-24 
PAR,  11-25  to  11-26 
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task,  5-11 
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structure 

considerations  In  creating, 

3-1 
most  effective,  3-2 
multlplo-Lree,  3-18 
multiply  defined  global 

symbol,  3-16 
specifying  library  search 
In  a,  10-23 
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ambiguously  defined,  3-16 
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for  I-  and  D-space  task,  7-7 
Overlay  tree  diagram 

virtual  address  space,  3-24 
OVIDC  module,  5-52 
OVIDL  module,  5-52 
OVIDR  module,  5-52 
$$OVRS 

reserved  PSECT  name,  E-3 

Page  Address  Register 

See  PAR 
Page  Description  Register 

See  PDR 
PAR,  2-16 

option,  11-25 
PAR  option,  11-26 
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use  of 

in  ODL,  3-24 
Partition 

declaring,  11-25 

in  region,  5-28 

naming    for    target    system,    C-1 

option,    11-25 

requi  rement 

shared  region,  5-3 

requi  rements 
region,  5-2 

si  ze 

for  TKB,  F-2 

specifying    for    region,    5-28 
Patch 

D-space,    11-13 

declaring  an  object  level, 
11-5 

global  relative,  11-19 
Path  loading,  4-3  to  4-4 
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example  of,  4-4 

in  autoload,  4-3  to  4-4 
$$PDLS 

PSECT,  5-52 

reserved    PSECT  name,    E-3 
PDR,    2-16 
Performance 

improving    TKB,    F-1 
Physical 

address,    2-13 

mapped  system,  2-17 
/PI  switch,  10-31 
/PM  switch,  10-32 
PMD  task 

installation  for  timely 
operation,  D-1 
Postmortem  dump,  D-1 

content,  D-3  to  D-5 

example,  D-2 

sample,  D-3  to  D-5 
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specifying  a,  10-32 
/PR  switch,  6-2,  10-33 
/PR:0  privileged  task,  6-2,  6-4 

to  6-5 
/PR:0  privileged  task,  uses  of, 

6-5 
/PR:4  privileged  task,  6-2,  6-4 

to  6-5 
/PR:4  privileged  task,  uses  of, 

6-5 
/PR:5  privileged  task,  6-2,  6-4 

to  6-6 
/PR:5  privileged  task,  uses  of, 

6-5 
PRI  option,  11-27 
Priority 
task 

declaring,  11-27 
Privileged  and  nonpr iv ileged 
task 
distinction  between,  6-1 
Privileged  task,  2-25,  6-1 
accessing 

Executive  with  a,  6-4 
I/O  page  with  a,  6-4 
building  a,  6-6  to  0-11 
comparison  of  nonpr ivi leged 

and,  6-1 
hazards  of  a,  6-1  to  6-2 
in  a  mapped  system,  6-1 
logging  off  from,  6-1 
MAC  command  sequence,  6-9 
map  of,  6-10  to  6-11 
mapping  of,  6-2  to  6-3 
/PR:0,  6-2,  6-4  to  6-5 
/PR:4,  6-2,  6-4  to  6-5 
/PR:5,  6-2,  6-4  to  6-6 
pre  cesser  trap  in  a,  6-2 
specifying,  2-25 
specifying  a,  6-2 
TKB  command  sequence,  6-10 
to  examine  unit  control  block, 
6-6  to  6-11 
Prog  ram 

development  step,  1-1 
limit,  A-i8 
section,  5-53 

additive  displaced 

relocation,  A-21 
additive  relocation,  A-20 
adjacency  requirement  for, 

10-46 
allocation,  2-2 
attribute,  2-4 
attribute  restriction,  2-3 
blank  ( .BLK) ,  2-3 
creation,  2-3 

displaced  relocation,  A-19 
element,  2-2 
extension  of,  11-14 
in  shared  region,  5-7 
making  autoloadable,  4-3 
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name,  2-3 
name  conflict,  5-7,  5-39  to 

5-40 
naming  restriction,  5-7 
ordering,  5-7,  10-36,  10-46 
overlay  allocation,  3-19 
relocation,  A-19 
resolution  of,  3-19 
resolving  names,  5-7,  5-39 

to  5-40 
resolving  names  in  region 

and  task,  5-16 
save  attribute,  2-7 
segregating,  10-36,  10-46 
sequential  ordering  of, 

10-36,  10-46 
space  allocation,  2-5  to 

2-6 
specifying  explicitly  in 

overlay,  3-29 
specifying  in  overlay,  3-19 
virtual,  5-53 
section  name,  A-7 

applying  autoload  indicator, 
4-3 
section  name  entry,  A-8 
section  name  flag  byte,  A-8 

to  A-9 
version 

identification,    A-10 
Program    section 
$$ALVC,    7-11 
$$ALVD,    7-11 
$$ALVI,    7-11 
I-   and   D-space    task 

overlay,    7-6 
multiuser    task 

I-    and    D-space,    9-3 
named 

in   region,    5-13 
virtual 

allocating    physical   memory 

to    a,    5-56 
attaching   virtual   attribute 

to    a,    5-56 
building   a    task    using,    5-58 

to    5-61 
creating   a,    5-56,    5-58    to 

5-61 
FORTRAN    run-time    support 

for,    5-56    to    5-57 
option    usage,    5-55 
specifying,    11-40 
specifying    base    address    for 

a,    5-56 
specifying    length,    5-54 
specifying    physical    size, 

5-54 
specifying    window   size, 

5-54 
support    for    a,    5-56    to   5-57 
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See  also  Program  section 

See  Program  section 
.PSECT  directive,  3-29 
PSECT  name 

•FCTR  directive 
argument,  3-26 
.PTLUN 

reserved  global  symbol,  E-2 

$$RDSG 

PSECT,  5-52 

reserved  PSECT  name,  E-3 
Region,  2-18 
absolute,  5-9 

building  precautions,  5-7 
mapping  for,  5-8 
mapping  of,  5-7 
specifying  an,  5-7 
symbol  definition  file,  5-9 
al location 

diagram,  5-20 
of  window  block  for,  5-25 
APR 

speci  f ying ,  5-6 
assigning  references,  5-23 
bui Iding 

a  linking  task,  5-21  to 

5-22 
and  linking  to  a,  5-14, 

5-17  to  5-18 
interaction  of  /CO/LI/PI 

switch,  5-3 
options 

in  an  overlaid,  5-10 
options  in  an  overlaid, 

5-11 
use  of  /CO/LI/PI  switch, 

5-3 
with  PAR  option,  5-2 
common,  2-19  to  2-20 
descriptor,  B-21 
descriptor  in  overlay,  3-20 
dynamic,  2-20,  5-40  to  5-43 
building  a  task  that 

creates  a,  5-40  to  5-43 
installing  in  RSX-llM,  5-2  to 

5-3,  5-20 
installing  in  RSX-llM-PLUS, 

5-2  to  5-3,  5-20 
library,  2-20 
linked  to  a  region,  5-26 
linked  with  a  region,  5-25 
linking  to  a,  5-13  to  5-14, 

5-26 
map,  5-19 

mapping  of  an  absolute,  5-7 
memory-resident  overlaid,  5-9 
building,  5-9 
example  of  building,  5-10 
number  of,  5-17 
options  for  building,  5-17  to 
5-18 
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Region  (Cont.) 

options  for  linking  to,  5-14 
overlaid,  5-9 

autoload  call  overhead, 

5-13 
autoload  in,  5-13 
autoload  vector,  5-11 
FTB  and  old  libraries,  5-13 
global  symbols  in  .STB  file, 

5-11 
I-  and  D-space  task  vectors, 

5-11 
named  program  section,  5-13 
run-time  support  for,  5-12 

to  5-13 
.STB  file,  5-11 
partition,  5-28 

requirements,  5-2 
procedure  for  building  a, 

5-17  to  5-18 
program  section  in,  5-7 
PSECT 

building  a  linking  task, 
5-23 
relocatable,  5-5 
mapping,  5-5 
specifying,  5-5 
specifying  APR  for,  5-6 
.STB  file  for  a,  5-9,  5-14, 
5-16 
resident  relocatable,  5-5 
resolving  PSr.CT  names,  5-39 

to  5-40 
shared,  2-20,  5-1 

allocation  of  window  block 

for,  5-14 
autoload  vectors  in,  5-12 
defined,  5-1 
initializing  window  block 

for,  5-14 
installing,  5-16 
partition  requirement,  5-3 
resolving  PSECT  names,  5-16 
restrictions  for  overlaid, 

5-12 
symbol  definition  file, 

5-16 
use  of  /CO/LI/PI  switches, 

5-9 
windows  in,  5-14 
size  of,  5-17 
speci  f ying 

as  position  independent, 

lC-9,  10-31 
partition  foi ,  5-28 
.STB  file,  5-4  to  5-5,  5-14, 
5-16 
for  an  absolute,  5-7,  5-9, 

5-12 
using  /CO/LI/PI  switches, 
5-4 
symbol  definition  file,  5-9 
task,  2-18  to  2-20 


Region  (Cor.t.) 

task  building  options,  5-13 

to  5-14 
type  of  access  to,  5-14 
use  of  /CO/LI/PI  switches, 

5-5 
window,  5-15,  5-25 
with  linked  task 

in   I-    and   D-space   system, 
7-3 
Relocatable    region 

See  Region 
Relocation 
code,  2-4 
complex,  A-22 
entry,  A-23 
operation  codes,  A-22 
directory  command  byte,  A-13 
directory  record,  A-12 
entries,  A-12  to  A~13 
format,  A-14 
displaced 

global,  A-16 
global ,  A-1 5 

additive,  A-16 
global  additive  displaced, 

A- 17 
internal  ,  A-1 4 

displaced,  A-15 
1  ibrary 

resident,  A-23 
program  section,  A-19 
additive,  A-20 
additive  displaced,  A-21 
displaced,  A-19 
resident  library,  A-23 
RESCOM 

linking  to  region,  5-14 
option,  11-28  to  11-29 
Reserved  symbol 

for  the  Task  Builder,  E-1 
Resident 
common 

name  block  data,  B-8 
1 ibrary 

name  block  data,  B-8 
relocation,  A-23 
memory 

for  TKB  performance,  F-3 
overlay  operator 

enabling  recognition  of, 
10-34 
region 

using  to  reduce  overhead, 
F-4 
Resident  region 
map  file 

including  symbol  definition 
in,  10-26 
RESLIB 

linking  to  region,  5-14 
option,  11-28  to  11-29 
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RESLIB 

option  (Cont.) 
In  supervisor- 
8-20  to  8- 
RESSUP 

option,  8-9,  11- 
use  in  CSM  lib 

8-8,  8-19 
use  in  supervi 
library,  8 
Restarting  TKB  opt 
$$RGDS 

reserved  PSECT  n 
RLSCT  FORTRAN  subr 

5-58 
/RO  switch,  10-34 
Root 

in  a  co-tree,  3- 
null,  3-31 

in  ODL,  3-31 
structure 

overlay,  3-21 
.ROOT  directive,  3 
.ROOT  statement 
allocation  diagr 
creating  from, 
ROPAR  option,  11-3 
$$RTQ 

PSECT,  5-52  to 
reserved  PSECT 
$$RTR 

PSECT,  5-52  to 
reserved  PSECT 
$$RTS 

PSECT,  5-53 
reserved  PSECT  n 
Run-time  support 
overlaid  region, 
autoload,  5-13 
autoload  call 

5-13 
FTB  and  old  11 
named  program 
5-13 


mode  library, 
21 

31  to  11-32 

rary,  8-3, 

to  8-21 

sor-mode 

-7 

ion,  11-4 

ame,  E-3 
outine,  5-56, 


31 


-23 

am 

3-37 
3 

-53 
ame,  E-3 

-53 
ame,  E-4 


ame,  E-4 

5-12  to  5-13 

overhead , 

braries,  5-13 
sections. 


Save  attribute,  2-4 
SCAL  to  CSM  library 

converting,  8-20 
Scope-code,  2-4,  2-7 
/SE  switch,  10-35 
Segment 

autoloadable 
data,  4-7 

global  symbol  in,  4-4 
call,  3-10 

to  up-tree,  4-6 
definition  of  a,  3-1 
descriptor,  B-19 

I-  and  D-space  task,  7-11 
in  overlay,,  3-20 
limiting  number 

reducing  overhead,  F-4 
loading 


Segment 

loading  (Cont.) 

as  part  of  co-tree,  4-2 
when  called,  4-4,  4-6 
making  autoloadable,  4-3 
mapping,  2-10 

disk-resident,  2-11 
memory-resident,  2-12 
multiple,  3-5 

global  symbol  in,  3-16 
global  symbol  resolution, 

3-17 
symbol  resolution,  3-16 
name 

applying  autoload  indicator 

to,  4-3 
. FCTR  directive  argument, 
3-26 
null 

in  ODL,  3-31 
overlay 

arrangement,  3-15 
iToot  structure,  3-21 
symbol  processing,  3-17 
processing  order,  3-17 
single,  3-4,  3-8 
up-tree 

I-  and  D-space,  3-22 
Semicolon  (; ) ,  1-8 
SEND  directive 

enabling  for  your  task,  10-35 
/SG  switch,  10-36 
$$SGDO 

PSECT,  5-53 

reserved  PSECT  name,  E-4 
$$SGD1 

reserved  PSECT  name,  E-4 
$$SGD2 

PSECT,  5-53 

reserved  PSECT  name,  E-4 
/SH  switch,  10-37 
Shared  region,  5-1 

See  Region 
Single  segment  task,  3-8 
/SL  switch,  10-44 
Slash 

double  (//) ,  1-6 
single  {/) ,  1-5  to  1-6 
Slow  TKB 

to  improve  overhead,  F-11 
$$SLVC 

reserved  PSECT  naie,  E-4 
SNAP$  macro,  D-6 
format  of,  D-8 
Snapshot  dump,  D-5  to  D-6 
example  of,  D-10  to  D-12 
format  of  macro  for  creating, 
D-7 
SNPBK$  macro,  D-6 

fornat  of,  D-7 
SNPDF$  macro,  D-6 
/SP  switch,  10-45 
/SQ  switch,  10-46 


m 
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/SS   switch 

symbol    definition    file 
reducing   overhead,    F-4 
SST  vector   address 
declaring,    11-27 
Stack 

declaring   size,    11-34 
supervisor-mode,   8-20 
STACK   option,    11-34 
.STB    file,    5-9 

absolute   region,    5-7,    5-9 
content   of   a,    5-5 
excluding    symbol    from,    5-11 
for    region,    5-4    to   5-5,    5-14, 

5-16 
I-   and    D-space    task,    7-9 
including    symbol    in,    5-11 
interaction   of   /CO/LI/PI 

switches,    5-4 
overlaid    region,    5-11    to   5-12 

global    symbols    in,    5-11 
program    sections,    5-16 
program   sections    in,    5-5 
relocatable    region,    5-9,    5-16 
use   of    /CO/LI/PI    switches, 
5-5,    5-9 
Structure 
In   TKB 

size   of,    F-3 
.SUMLl 

reserved  global  symbol,  E-2 
Supervisor-mode,  2-24 
library,  2-24 
See  Library 
mapping,  2-24,  2-26  to  2-27 
mode  switching,  8-8,  8-12  to 

8-13 
stack,  8-20 
SUPLIB 

option,  8-9,  11-35 

use  in  CSM  library,  8-3, 

8-19 
use  in  supervisor-mode 
library,  8-7 
Switch 

conflict  In,  10-1 
default 

modifying,    F-7    to    F-11 
modifying   default   of,    F-7    to 

F-11 
summary,    10-2    to   10-4 
syntax,    10-1 
Task    Builder,    10-1 
/AC[:n]  ,    10-5 
/AL,    10-6 
/CC,     10-7 
/CM,    10-8 
/CO,    10-9 
/CP,    10-10 
/CR,    10-11    to    10-13 
/DA,    10-14 
/DL,     10-15 
/EA,    10-16 


Switch 

Task  Builder  (Cont.) 
/EL,  10-17 
/FP,  10-18 
/FU,  10-19 
/HD,  10-20 
/ID,  10-21 
/IP,  10-22 
/LB,  10-23  to  10-24 
/LI,  10-25 
/MA,  10-26 
/MM,  10-27 
/MP,  10-28 
/MU,  10-29 
/NM,  10-30 
/PI,  10-31 
/PM,  10-32 
/PR[:n] ,  10-33 
/RO,  10-34 
/SE,  10-35 
/SG,  10-36 
/SH,  10-37 
/SL,  10-44 
/SP,  10-45 
/SQ,  10-46 
/SS,  10-47  to  10-49 
/TR,  10-50 
/WI,  10-51 
/XH,  10-52 
/XT(:n] ,  10-53 
Symbol 

affecting  search  for,  2-7 
declaration  flag  byte,  A-7 
definition  file 

excluding  symbol  from  a, 

11-21 
for  system-owned  region, 

11-11 
for  user-owned  region, 

11-29 
Including  symbols,  11-18 
reducing  overhead,  F-4 
directory  record 

declare  global,  A-2 
end  of  global,  A-11 
internal ,  A-24 
full  search  in  overlays 

specifying,  10-19 
global 

address  of  ODT  SST  routine, 

11-24 
ambiguously  defined  in 

overlay,  3-16 
declaring  definition  In  a 

task,  11-17 
default  library  resolution, 

3-18 
directory  record,  A-2 
directory  record  format, 

A-4 
end  of  directory  record, 

A-11 
excluding  in  a  task,  11-21 
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Symbol 

global  (Cont.) 

from  the  default  library, 

3-18 
In  autoloacial>le  segment, 

4-4,  4-6 
in  cross-reference  listing, 

10-12  to  10-13 
including  In  a  task,  11-18 
multiplydef ined  ,  3-16 
multisegment  task,  3-16 
name,  A-6 
name  entry,  A-6 
overlaid  region  .STB  file, 

5-11 
overlay  search  sequence, 

3-17 
resolution,  2-7,  3-17 
resolution  in  co-tree,  3-17 
resolution  in  multisegment 

task,  3-16 
undefined,  2-7 
in  cross-reference  listing, 

10-12 
internal 

autoloadable  library,  A-26 

to  A-27 
end-of-module ,  A-30 
end-of-module  format,  A-32 
global,  A-28 

internal  symbol  name,  A-30 
internal  symbol  name  format, 

A-31 
line-number,  A-29  to  A-30 
literal  record-  ;.  30 
literal  record  forn-.ct,  A-31 
module  name,  A-27  to  A-28 
overall  format,  A-24  to 

A-25 
PC  correlation,  A-29  to 

A-30 
PSECT  item,  A-29 
relocatable/relocated,  A-27 
start-of-segment ,  A-25  to 

A-26 
task  identification,  A-26 
TKB  generated,  A-25 
name  entry 

internal,  A-5 
number  of  processed  for 

performance,  F-3 
reserved  for  the  Task  Builder, 

E-1 
resolving 

overlay  region,  5-11 
search 

selective,  10-47  to  10-49 
Symbol  definition 
SYSLIB.OLB,  2-7 
Symbol  definition  file 
See  also  .STB  file 
supervisor-mode  library 
system-owned,  11-35 


Symbol  definition  file 
supervisor-mode  library 
(Cont.) 
user-owned,  11-31 
Syntax  rule 

summary  of,  l-lO 
SYSLIB 

Including  contribution  in  map, 

10-26 
linking  to 

by  supervisor-mode 

libraries,  8-2,  8-7  to 
8-9,  8-18 
replacing  as  default,  10-23 
SYSLIB.OLB 

for  symbol  definition,  2-7 
System 

host  and  target,  C-1 
mapped,  2-14 

physical  and  virtual  space, 
2-15 
object  module  library,  2-2 
See  also  Library 
See  also  SYSLIB.OLB 
target 

memory  management,  10-27 
unmapped,  2-14 
System-controlled  partition 
extending  memory  for  task  in, 
11-15 

T-bit  trace  trap,  10-50 
Table  storage,  F-2 
memory  for 

to  improve  performance,  F-2 
Target  system,  C-1 

transfering  task  to  a,  C-1 
Task 
access 

system-owned  common  or 

library,  11-11 
system-owned 

supervisor-mode  library, 
11-35 
user-owned  common,  11-28 
user-owned  library,  11-28 
user-owned  supervisor-mode 
library,  11-31 
active  files 

declaring  number  of,  11-6 
additional  memory  for,  11-15 
address  windows 

declaring  an  additional, 
11-41 
ancillary  control  processor 

specifying  as,  10-5 
assigning  physical  device  to 

LUN,  11-7 
attaching  slave  attribute  to, 

10-44 
building  for  target  system, 

C-1 
changing  name  of,  11-36 
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Task  (Cont.) 
checkpointable 

specifying,  10-10 
command  line  to  build  a,  1-2 
comparison 

conventional  and  I-  and 
D-space,  7-2 
completion  routine  for  a, 

11-10 
conventional 

autoload  vector,  B-17 
disk  image,  7-6 
mapping  compared  to  I-  and 
D-space  task,  7-2 
creating  a  dynamic  region, 

5-40 
creating  multiuser,  10-29 
D-space 

overlay  structure,  3-21 
data 

in  task  image,  B-4  to  B-6 
needed  by  system  to  install, 
B-1 
declaring 

execution  priority  for, 

11-27 
maximum  stack  size  of, 

11-34 
number  of  LUNs  for,  11-39 
object-level  patch  for, 

11-5 
ODT  SST  vector  in,  11-24 
disk  image,  2-8 
enabl ing 

postmortem  Dump  for,  10-32 
T-bit  trace  trapping  in, 
10-50 
extending 

a  program  section  in  a, 

11-14 
memory  of,  11-15 
to  partition  length,  11-15 
external  header 

specifying,  10-52 
floating  point  processor  in 

specifying,  10-18 
format  buffer 

declaring  length  of,  11-16 
global  relative  patch 

declaring,  11-19 
global  symbol 

excluding  a,  11-21 
including  in,  11-18 
global  symbol  definition 

declaring  a ,  11-17 
global  symbol  reference 

declaring  a,  11-20 
header,  2-8 

allocating  additional 

(checkpoint)  space  in, 
10-6 
checkpoint  area  within,  B-9 


Task 

header  (Cont.) 

controlling  creation  of, 

10-20 
fixed  part,  B-11  to  B-12 
I-  and  D-space,  7-11 
space  for  EAE  context, 

10-16 
space  for  floating-point 
context,  10-18 
host  to  target  system 

example  of  transferring, 
C-2 
I-  and  D-space,  2-28,  7-1 
autoload  vector,  7-9,  B-17 

to  B-18 
differing  from  conventional 

task,  2-28 
manual  load  calling 

sequence,  4-8  co  4-9, 
4-11 
map,  7-9 
mapped  in  T-  and  D-space 

system,  7-4 
mapping,  7-3 
mapping  summary  of,  7-2 
memory  allocation,  7-9 
overlaid,  7-5 

overlay  region  vector,  5-11 
overlay  structure,  3-21 
patching,  11-13 
PSECT  in  overlay,  7-6 
simplified  mapping,  2-29 
specifying,  10-21 
.STB  file,  7-9 
with  up-tree  segment,  3-22 
I-and-D  and  conventional 

mapping  compared,  7-2 
identi  f ication 

for  I-  and  D-space,  7-1 
identifying  partition  for, 

11-25 
image,  B-1,  B-14 

file  structure,  B-1 
image  on  disk 

non-overlaid,  B-2 
non-overlaid  as  Ikinked  to 

library,  B-2 
overlaid,  B-3 
overlaid  I-  and  D-space, 
B-4 
including  debugging  aid  (ODT) 

in,  10-14 
inhibiting  queuing  message  to, 

10-35 
installed  name 

declaring,  11-36 
label  block,  2-8 
label  block  0,  B-7 
label  block  1,  B-9 
label  block  2,  B-9 
label  block  3,  B-9 
1  inking 
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Task 

linking  (Cont.) 

to  a  supervisor-mode 

library,  8-10  to  8-12 

to  region,  5-13 

to  region  in  I-  and  D-space 
system,  7-3 

to  several  libraries,  11-8 
to  11-9 
list  o£  attributes,  10-37 
logical  units 

number  of,  11-39 
making  checkpointable,  10-6 
map 

linked  to  a  common,  5-24 
mapping,  2-15,  2-20 
maximum  record  buffer  size 

declaring,  11-23 
memory,  2-10 
memory-resident  overlay 
operator 

enabling,  10-34 
memory-resident  overlay 
segment 

changing  alignment  of,  10-8 
multisegment ,  3-5 

global  symbol  resolution, 
3-17 
multiuser,  2-28 

See  Multiuser  task 

declaring  read-only 
piirtition,  11-33 

specifying  a,  10-29 
ODT  vector,  11-24 
overlaid,  3-7,  3-9 

global  cross-reference  of, 
4-12  to  4-14 

memory  savings,  3-9  to  3-10 

segment  calls,  3-10 

virtual  address  space,  3-10 
overlaid  1-  and  D-space 

disk  image,  7-8 

map,  7-12  to  7-16 

tree,  7-7 

virtual  address,  7-7 
overlay,  2-10 
parti  tion 

declaring,  11-25 
patching  of 

with  object  code,  11-5 
privileged,  2-25 

See  Privileged  task 

specifying,  2-25 

specifying  a,  10-33 
privileged  access  right  for 

establishing,  10-33 
program  section  order 

effect  In  creating,  10-36, 
10-46 
region,  2-18  to  2-20 
relocation  of,  2-2 
resident  common 

system-owned,  11-11 


Task    (Cont.) 

resident    library 

system-owned,    11-11 
single    segment,    3-4,    3-8 
slave 

specifying    a,    10-44 
sped  f  ications 

multiple,    1-5 
sped  f  ylng 

data    space    in   an    I-   and 

D-space,    7-5 

KEll-A    in,    10-16 

SST  vector  address 

declaring,  11-37 

stack  size 

declaring,  lJ-34 
structure,  2-8 

label  block,  2-8 
supervisor-mode  library  for  a, 

11-31,    11-35 
system   mapping    status   of 

Indicating,    10-26 
time-based    schedule    request 

declaring  UIC  for,  11-38 
traceable 

specifying  a,  10-50 
UIC 

declaring,  11-38 
use  of  memory  management, 

2-15  to  2-16 
user 

data  space  definition,  7-1 
vector  address 

declaring  system  SST  trap, 
11-37 
virtual  program  section 

specifying,  11-40 
window,  2-20  to  2-22 
in  I-  and  D-space,  7-5 
linking  to  region,  5-15 
Task  Builder 

command  line,  1-2 
fast 

See  Fast  Task  Builder 
function,  2-1 
option,  1-4 
switch,  10-1 
TASK  option,  11-36 
Text  information  record,  A-11 
to  A-12 
format,  A-12 
Throughput 

improving  TKB,  F-1 
TKB 
slow 

to  improve  performance, 
F-11 
/TR  switch,  10-50 
Transfer 

address,  A-6 
address  entry,  A-6 
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Tree 

applying  autoload  indicator, 

4-2 
calling  segments  in,  4-6 
calling  up-tree  segments,  4-6 
multiple 

defined,  3-30 
defining,  3-31 
structure,  3-18,  3-32 
.TRLUN 

reserved  global  symbol,  E-2 
$$TSKP 

reserved  PSECT  name,  E-4 
TSKV  option,  11-37 
Type-code,  2-5,  2-7 

UFD  conventions  in  command  line, 

1-9 
UIC 

declaring  in  task,  11-38 

option,  11-38 
UNITS  option,  11-39 
Unmapped 

system,  2-14 

memory  layout,  2-16 
Unnamed  program  section 

See  Program  section 
.USLUl 

reserved  global  symbol,  E-2 
.USLU2 

reserved  global  symbol,  E-2 

Vector 

autoload,  3-20,  4-4 

conventional  task,  B-17 
eliminating  unnecessary, 

4-6 
I-  and  D-space,  7-11 
I-  and  D-space  format,  4-5 
I-  and  D-space  task,  7-9, 

B-17 
in  region,  5-12 
in  task  header 

extension  area  format,  B-13 


Vector  (Cont.) 
mode- swi  tching 

supervisor  library,  8-19 
supervisor-mode  library, 
8-1 
ODT,  11-24 
overlaid  region,  5-11 

I-  and  D-space  task,  5-11 
SST  address,  11-27 
$VEXT 

low-memory  context,  B-10 
reserved  global  symbol,  E-2 
VSECT  option,  11-40 

/WI  switch,  10-51 
Window,  2-20  to  2-22 
block,  2-20  to  2-22 
creating  a,  5-14 
for  a  region,  5-14 
in  overlay,  3-49 
definition  block,  2-22 
descriptor,  B-20  to  B-21 

in  overlay,  3-20 
for  region  and  linking  task, 

5-15 
in  I-  and  D-space  task,  7-5 
option,  11-41 
region,  5-25 
wrap  around 

in  virtual  sections,  5-54 
$$WNDS 

reserved  PSECT  name,  E-4 
WNDWS  option,  11-41 
Work  file 
accesses 

system  overhead,  F-2 ,  F-5 
to  F-7 
parameters  for,  F-2 
performance 

changing  device  to  improve, 
F-5 

/XH  switch,  10-52 
/XT  switch,  10-53 
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